Design Practice Repository (DPR) and eBook Completed

8 activities + 15 artifacts templates for agile software engineers

News (September 2024): Our public Design Practice Repository (DPR) and the corresponding eBook “Design Practice Reference“ on LeanPub collect proven method elements for agile architecting in general and API/service design in particular. Version 1.5 of the GitHub repository is available now, and the eBook stands at 100% completion. Voucher at the end of the story!

Why DPR? What’s In It?

I appreciate methods as enablers; see this post for rationale backing my 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):

Architectural Modeling activity and its consumed/produced artifacts

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).

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:

LeanPub landing page for DPR

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.5 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 finished and enters maintenance mode now.

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 story for examples).
• Check out Chapters 1 and 5 in the eBook for motivation and adoption hints (with examples).
• Review the Cheat Sheet in the Appendix of 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)

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

Originally published at https://ozimmer.ch on February 7, 2023.

© Olaf Zimmermann, 2023–2024. All rights reserved.