Design Practice Repository and Reference (DPR)

A Collection of “Mighty” Method Elements on GitHub and Leanpub

Real-World Architecture Metaphor: Repositories, Artifacts/Building Blocks, Patterns, Architectural Style(s)

The Design Practice Repository (DPR) on GitHub compiles proven method elements and other knowledge nuggets for API and (micro-)service design — and more general software architecture work.

Update (January 31, 2023): Five new artifact templates are available in Version 1.4 of DPR: Quality Attribute Scenario, Context Diagram, Overview Diagram, Component Diagram and Deployment Diagram.

Update (November 2, 2022): The DPR ebook stands at 91% progress now. We fixed some editorial mistakes, added a third usage example (from the PfAD book), and updated metadata. Next up is adding five missing artifact templates (from the backlog)!

Update (May 21, 2021): The DPR content also comes as an ebook now. The current draft (80% complete) is available on Leanpub.

Update (December 8, 2020): Story splitting and CRC cards now featured, tutorial enhanced with architecture decision record(s), many elements edited and additional background information provided.

Methods: The Good, The Bad and The Why

Read on if you agree:

We all learn well from mistakes — but do these mistakes have to be our own?

You might be thinking that methods (and patterns) are on the other side of cool in the age of Agile, search engines and online developer communities. Who likes to be bossed around by stiff processes and forms? Why not simply look up solutions to problems online? Well, it depends on the problem at hand whether such ad-hoc approach is effective and efficient.[1]

My Personal Take. Methods can actually be cool or even likable, instrumental, trustworthy — when engineered and applied properly. They should have an Enabling Attitude rather than a Directing one.[2] I appreciate guides and advice that come across as friendly mentors.

Why am I open to such advice? I want to be efficient in anything I do. Specifically in software analysis, design and development, I want to get to the domain- and technology-specific work as soon as possible; the less time I have to spend on establishing and agreeing on document structures and notations, the better. On the other hand, I do not want to forget anything important — for instance, a question to a key stakeholder when assessing the architectural significance of a requirement or design issue. More generally speaking, I am always curious and want to improve my practices continuously.

I view methods as tour guides rather than lawyers[4]. And after more than 25 years in IT and software development, I decided to become a tour guide and started to compile a collection of method elements. To make things even more interesting, I teamed up again with Mirko Stocker, an agile full stack developer from generation Y.

Enter: Design Practice Repository (DPR)

Let’s start with some “rules” of method engineering (and adoption)[5]:

1) Context matters. What works well for one role in a particular client, team and project environment might be a major source of headache and trouble elsewhere. Any General Advice should make its context and usage criteria and limitations explicit.

2) If in doubt, leave it out. Do not create a “big ball of method mud”; always have a distinct target audience and its information needs in mind when creating a template or other method element. Test your creations yourself before release.

3) Value purpose/usefulness over compliance. Do not follow templates and process advice by the book, but adopt them to your needs. No blind obedience or cargo cults please!

So much of what you will find in DPR is not new at all but mined from existing practices and experience, just like our (micro-)service API design patterns; similar to patterns, all DPR method elements are structured according to templates. If you are familiar with some of the method elements, view the repo as an online reference book that connects the dots between the knowledge nuggets, and provides fresh examples and motivating stories.

Going Even Deeper

a.k.a. Where to start exploring? How do I find checklists and templates?

DPR is organized around artifacts, templates, activities and techniques, which are produced, applied and performed by team members taking one or more software engineering roles:

Domain Model of DPR: Artifacts come out of Activities that are supported by Techniques and Templates.

The artifacts and templates folder is a good first stop; you might want to check out our Y-shaped Architecture Decision Records. Next up would be activities and techniques: The Stepwise Service Design (aka Contract First) practice assembles practice assembles method elements relevant for (micro-)service API design, including a Candidate Endpoint List.

Example of an Artifact and Template (aka Work Product). DPR proposes a very basic use case template to capture actor-system interactions. You find both the template and an example, as well as a rather opinionated section on hints and pitfalls to avoid, in the Use Case method element:

# UC 1: Name
Pre: ___
1. The user ___
2. The system ___
...
Post: ___

Lean enough? I would hope so. And yes, we do feature agile User Stories too.

Sample Activity and Technique (aka Process Step). DPR suggests four steps of Architecture Modeling with a diverse set of inputs and outputs:

Four Types of Architecture Diagrams: Context (Black Box), Architecture Overview, Component, Deployment

The first three steps match the context, container, and component diagrams in the C4 Model; the last step takes an operational viewpoint.

Status and Scope of DPR. Version 1.4 of DPR contains a total of two roles, eight activities from SMART NFR Elicitation to Stepwise Service Design, and 15 artifact templates (also serving as checklists). A quick start tutorial takes you through the repository structure in a small sample scenario.

Really Mighty and Enabling?

Back to the method rambling from above:

Does DPR expose an enabling or directing attitude? As a self-experiment, I went into the DPR repo and searched globally for “must” when preparing this post. This rather assertive verb is only used in the template instructions and the terms and conditions for contribution, not in the method content. Searching for “have to” yields a similar result. There are two exceptions: “API and service design have to be implemented” and “technology concepts also have to be decided” (and these two statements hopefully will not offend anybody) 😅.

Let’s now see how DPR does w.r.t. Michael Keeling’s criteria for Mighty Methods:

1. Facilitate human-centered design. DPR does not target User Experience (UX) specifically but software architects and developers. Developer Experience (DX) matters! This target audience is made explicit in the roles, according to method creation and adoption rule 2 from above.
2. Bias toward concrete outcomes. I would hope that every method and method element does this; selling services or courses should not be the primary motivation. The artifacts and templates folder in the DPR repository is full of suggested outcomes! The Definition of Done for Architectural Decisions that I proposed in another story can take a supporting role (and might appear in a future version of DPR).
3. Consider the whole design space. DPR goes from (non-)functional requirements to architectural decision making and architecture modeling. Admittedly, not much focus is on deployment and infrastructure design yet (but these topics are mentioned in the fourth modeling step).
4. Promote team growth. Hopefully the method elements are written in a compact and engaging style and can be applied without much further coaching. Hints on what make an instance of the method element useful (or not) are included.
5. Easy to teach, fun to use. I do teach many of the method elements on bachelor and master level, as well as in continued education and client workshops. I would not necessarily say that this is easy, but concrete examples and motivating project stories help. I’ll let you judge the “fun to use” part of the criterion. 😉

Wrap Up and Outlook

Our recently released Design Practice Repository (DPR), pronounced “deeper”, is a public GitHub repository that collects and references practices and artifacts from various software engineering and architecture design methods (old and new). For instance, it explains how to specify quality attributes in a SMART way, how to apply strategic and tactic Domain-Driven Design (DDD) and how to capture design decisions. Watch out for summaries of the client-server-cutting (layer-tier distribution), context diagrams, component modeling and interaction diagrams in future versions.

Getting Involved. I hope that by now you agree that DPR is likable, instrumental, trustworthy (lit)? Do you miss an artifact template or activity that qualifies as a mighty method in your personal toolbox?
Contact me to get involved!

– Olaf (a.k.a. ZIO)

PS: A longer version of this post is available in the “The Concerned Architect”.

Acknowledgements

I would like to thank Mirko Stocker for his contributions to DPR as well as Stefan Kapferer and Oliver Kopp for their reviews. And I would like to thank all my former clients, peers and mentors (for instance, at ABB and IBM) for letting me architect for and with them, and learn from them along the way.

Notes

1. You’ll probably not take a topographic map and a first-aid kit with you when you go to the nearest supermarket, but what if you head for a multi-day hiking trip in the Alps?
2. Does the “should” in this sentence already violate the principle? 😉
3. This method (that has never been fully published publicly) also had a work product called ARC-100 advising us to capture our architectural decisions — long before Tyree/Akerman and Nygard wrote about this topic. But that’s another story.
4. Another analogy would be sports — coaches and referees are best if not noticed, but a great game takes place and attention is on the players.
5. Am I directing or enabling here? Well, these are rules I have set for myself as method engineer, so I’d say it is ok to be a little more assertive than in the actual method content.

© Olaf Zimmermann, 2020–2022. All rights reserved.