Design Practice Repository and Reference: GitPages and eBook Enhanced

Our public Design Practice Repository (DPR) and the corresponding eBook at LeanPub collect proven method elements for agile architecting in general and API/service design in particular. Version 1.4 of the GitHub repository is available now, and the eBook stands at 96% completion.

Why DPR? What’s In It?

I appreciate methods as enablers; see this post for rationale backing this position. Having applied and adopted existing design practices in a “best-of-breed” manner pretty much since somebody called me an architect around 1995, I decided to curate a go-to-guide of my favorite method elements. To limit bias and enjoy writing, I teamed up with Mirko Stocker.

DPR, pronounced “deeper” collects practices and artifacts from various software engineering and architecture design methods (old and new) that are applicable to service analysis, API design and beyond. DPR summarizes them and adds explanations when and why I use these particular method elements — and how. While there are some new elements, a lot of common wisdom is included deliberately. For instance, we explain how to specify quality attributes in a SMART way and how to apply strategic Domain-Driven Design (DDD).

The use cases for DPR include:

1. Decide whether or not to use a practice in a given problem, project, product context.
2. Recapitulate how to apply a practice and what (not) to put in an artifact.
3. Find pointers to tutorials and trainings about these method elements.
4. Serve as checklist and referee when revising or reviewing specifications and models.
5. Share all these insights with team members and colleagues.

DPR is organized around artifacts templates and activities, which are produced, applied and performed by team members taking one or more software engineering roles. Let’s look at sample content.

Sample Content

DPR suggests four steps of architecture modeling with a diverse set of inputs and outputs (yielding an informal workflow):

Five new artifact templates became available in Version 1.4 of DPR:

• A Quality Attribute Scenario specifies a specific and measurable quality goal for a particular context.
• A Context Diagram provides an outside view on a single system, including incoming and outgoing relations with other systems. It does not unveil any system-internal design.
• An Overview Diagram provides an overview of logical and physical building blocks that are refined in other types of diagrams. Unlike the context diagram, it looks inside a system, picking up all external interfaces (with human users, with other systems).
• A Component Diagram zooms into an element from an architecture overview diagram and shows its logical building blocks and their relations.
• A Deployment Diagram depicts a runtime configuration of a software-intensive system, consisting of physical elements such as compute nodes, storage units, and network connections. It may include information about the placement of application parts as well as systems management devices.

If all this sounds familiar to you, that’s because these particular artifact types have been around and proven useful for a long time, as covered by the sections “Origins and Signs of Use” (example: Context Diagram). What you will not find everywhere (at least not in this form) are our “Hints and Pitfalls to Avoid (Common Pitfalls)”, which report personal experience in industry projects and teaching (example: Deployment Diagram).

Meta Level: Common Structure

All role, activity and artifact descriptions are structured in the same way. These structures blend terminology from OMG SPEM and existing methods and take some inspiration from the Agile Alliance Glossary. They progress from context and motivation to input, steps and output to templates/checklists/how tos to examples. Origins and signs of use are also discussed, and pointers to other parts of DPR and other methods provided. A word budget is in place to keep this reference material as short as possible.

Here is the one for artifacts (shortened a bit):

Artifact/Template: *NN*
-----------------------
also known as: TODO

> *Synopsis: TODO* <!-- one line, glossary style definition -->

### Motivation (Addressed Information Need) 
<!-- Purpose -->
TODO

### Usage (Produced and Consumed When)
<!-- Must identify the producing role and the target audience; specify activity too -->
TODO 

### Template Structure and Notation(s)
<!-- What to do, artifact to produce; minimum, medium maximum diligence/verbosity -->  
TODO

### Example(s)
<!-- Must be concrete, ideally one for each verbosity/fidelity level basic, medium, full -->
TODO

### Tools and Notation
<!-- Should call out capabilities on beginner, intermediate, advanced level -->
TODO

### Hints and Pitfalls to Avoid
<!-- Don’t overdo etc. -->
TODO

### Origins and Signs of Use
<!-- From PLoPs and from AA -->
TODO

### Related Artifacts and Practices (incl. Alternatives)
<!-- in DPR and elsewhere -->

### More Information
TODO

Let me end this section with three tips for template evolution (and any form, actually): 🙂

1. Fill the first version out yourself to get a feel for the effort.
2. When adding something, try to eliminate something else.
3. If in doubt, leave it out.

More Examples

The sample content of our eBook features the Architectural Decision Capturing activity and Y-Statements. It also includes the Preface to the book and its first chapter, the Introduction. This is the home page of the eBook:

Additional instances of filled-out artifact templates appear in other publications. For instance, Chapter 2 and 3 of our recently published book “Patterns for API Design” (Addison Wesley Professional 2022) contain a user story, a domain model, context and component diagrams, and Y-statements from a sample case.

Status and Next Steps

Version 1.4 of DPR, just released, contains a total of two roles, eight activities from SMART NFR elicitation to stepwise service design and 15 artifact templates (activities index, artifacts index). The corresponding eBook is almost finished now and enters quality assurance mode.

To get going, you might want to:

• Take a look at the workflow figures in the “Instructions” sections of the activities, for instance on AD capturing and Domain-Driven Design (strategic and tactic).
• Skim read the artifact synopses, followed by the application “Hints and Pitfalls to Avoid” (see section “Sample Content” earlier in this post for examples).
• Check out Chapters 1 and 5 in the Appendix of the eBook for motivation and adoption hints (with examples).
• Review the Cheat Sheet in the eBook, organized into task-activity-artifact triples.
• Go through one of the online tutorials.

Contact me or Mirko for more information and feedback. eBook coupons are available, by the way. Try this one for a complementary copy!

– Olaf (Zimmermann) with Mirko (Stocker)

PS: A slightly shorter version of this post is available on my blog on Medium.

Acknowledgements. We would like to thank Oliver Kopp, Moritz Lange and other early adopters for their feedback on early versions of DPR parts.