DPR: Open Source Repository and eBook Collecting Mighty Methods

The Design Practice Repository (DPR) on GitHub collects proven method elements and other knowledge nuggets for API and service design — and agile software architecture work in general. This post is themed why go DPR?, includes some method rambling and features excerpts from the DPR content.

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): Our book “Design Practice Reference” 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 (April 8, 2021): The DPR content also comes as an ebook now. The current draft version 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 on this:

We all learn well (if not best) from mistakes — but do these mistakes always 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.¹

My Personal Take. Methods can actually be cool or even lit (likable, instrumental, trustworthy) — when engineered and applied properly. They (and their creators) should have an “enabling attitude” rather than a “directing attitude” one.² I appreciate guides and advice that come across as friendly mentors; for instance, books and online posts by Gregor Hohpe and Rebecca Wirfs-Brock do — to name just two of my “listen-to-leaders” (I have more nominees).

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 do want to improve my practices continuously (life long learning!).

In this light, the instructor (called method exponent) that trained me in the “IBM Systems Integration Method” in the late 1990s (later renamed to “Global Services Method”, followed by “Unified Method Framework” and then “Agile with Discipline”) impressed me when he pointed out how important it is to trim down the method to the “minimum viable practices” right after he had introduced himself and the course objectives. There even was a dedicated method adoption workshop built in to make sure that the trimming actually does happen.³

So I view methods as tour guides rather than lawyers.⁴ And after more than 25 years in IT and software development, I decided to create one now — more precisely, a collection of method elements. To make things a little more interesting, I teamed up with Mirko Stocker, an agile full stack developer from generation Y with whom I can pair architect and co-author splendidly. Not because we always agree but because we share common values, have complementing experiences and discuss controversially-constructively to find solutions that balance conflicting requirements. That’s the way it should be!

Enter Design Practice Repository (DPR), Pronounced “Deeper”

Let’s start with my three “rules” for method engineering (and adoption):⁵

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, 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 — and when adopting it for a project. 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!

When it comes to extending a method, two more rules apply:

4) Do not reinvent the wheel, but look for existing templates (and tweak them as needed). Only create something new if you do not find what you are looking for (yes, looking for existing material takes time and can be less fun than inventing something on your own).

5) Acknowledge and reference your input properly. Notably, some popular books seem to violate this rule and get away with it (self citations do not count, by the way).

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.⁶ If you are familiar with some of the method elements, view our repository as an online reference book that connects the dots between the knowledge nuggets and provides fresh examples as well as motivating stories.

Going Even DPR

aka 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:

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 still emerging, inclusive Stepwise Service Design (contract first) practice assembles method elements relevant for (micro-)service API design (for instance, Candidate Endpoint List); patterns from Microservice API Patterns (MAP) and related languages are featured as well.

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

1
2
3
4
5
6
7
8
9
# 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 (yielding an informal workflow):

The first three steps match the context, container and component diagrams in the C4 Model; the last step takes an operational viewpoint. All diagrams can be expressed in informal notations, UML or DSL tools such as Context Mapper. By the way, do not hesitate to apply the method adoptions rules from above: leave out steps or perform them in other orders!

More Examples. Other posts feature DPR elements in action and provide additional examples (as well as candidate method elements):

• Architectural Significance Test and Some Core Decisions
• Y-Statements — A light template for architectural decision capturing on Medium
• A Complete Guide through Microservice API Patterns (MAP)

Status and Scope of DPR. Version 1.4 of DPR, just released, contains a total of two roles, eight activities from SMART NFR elicitation⁷ to stepwise service design and ten artifacts templates (or checklists). A quick start tutorial takes you through the repository structure in a small sample scenario, followed by a more comprehensive tutorial featuring an online shop scenario (that still is under construction).

Really Mighty and Enabling?

Back to the method rambling from above: Does DPR expose an enabling or directing attitude?⁸

As a first self-experiment, I went into the DPR repo (Version 1.1) and searched globally for “must” when preparing this post. I use this rather strong, assertive verb in the template instructions and the terms and conditions for contribution only, 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. the “Keeling Five” criteria that Michael established in his ECSA 2020 keynote “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 DPR is full of suggested outcomes! The “Definition of Done for Architectural Decision Making” that I propose in another post on this blog 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 step of the architecture modeling activity).
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 makes 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. And I’ll let you judge the “fun to use” part of the criterion.

Wrap Up

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) that are applicable to service analysis and design (and beyond). 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.⁹

I hope that by now you agree that DPR is likable, instrumental, trustworthy (lit)? Some use social media to stay current… and we hopefully go a bit DPR here. 😄

Getting Involved. Do you miss an artifact template or activity that qualifies as a mighty method in your personal toolbox? Contact me to get involved!

– Olaf (aka ZIO)

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

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

Notes