design-practice-repository

Summaries of artifacts, templates, practices, and techniques for agile architecting (DPR-mm) and service design (SDPR-nn).

DPR Git Pages Home — Activities Index — Artifacts Index — Roles Index

Design Practice Repository (DPR)

Welcome to Software/Service/API Design Practice Repository (DPR) (pronounced “deeper”)!

This public repository collects method elements and practices from various methods (old and new) that are applicable to service-oriented analysis and design (and beyond).

Target Audience

This repository targets the following software engineering roles, ordered from specific to generic:

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

DPR Concepts (Domain Model)

DPR contains three types of method/practice elements:

The activities and artifacts that we have collected so far are:

DPR Activities, Artifacts and their dependencies

There is an introductory blog post. And the quick start tutorial takes you through the repository structure in a small sample scenario. The deeper API design tutorial (in draft state) is a good starting point if you like to learn by example (and are willing to invest a little more time).

Bibliography

We also provide a bibliography.

Status

Version 1.4 adds five artifact templates as output of Architecture Modeling:

Version 1.3 was a content hardening and maintenance release.

Version 1.2, released on December 7, 2020, added one activity and one artifact:

Tutorial 1 also was enhanced, as well as several other activity and artifact descriptions. We also added (even) more pointers to background information.

We have copy edited all content, provided additional references, and updated various external links.

Books With a DPR Connection

Novemer 8, 2022: “Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges”, published in the Addison Wesley Signature Series curated by Vaughn Vernon, references DPR and features sample artifacts such as domain models, Y-statements, and API descriptions. Learn more.

April 8, 2021: The DPR content also comes as an ebook now. The current draft version is available on Leanpub.

Terminology Clarification

(Micro-)Services and SOA Definitions

According to Martin Fowler, a service is a component with a remote Application Programming Interface (API). And services and their APIs come in different sizes, hence an engineering approach to designing them is required. That’s all there is to say!

If you want more conceptual clarifications, see this blog post, this presentation, or this article for a definition of microservices and positioning as an implementation approach to SOA.

The Microservice API Patterns (MAP) website, introduction, and pattern papers go even deeper and introduce terms such as endpoint, operation, and message representations.

Situational Method Engineering

DPR applies a best-of-breed approach. Our metamodel adopts parts of Chapter 2 from “An Architectural Decision Modeling Framework for Service-Oriented Architecture Design”(SOAD):

DPR metamodel (from SOAD PhD thesis)

This terminology maps to that of other method engineers like this:

This repository Agile community (glossary) OMG SPEM 2.0 (PDF) Open Unified Process (UP) and other methods
Role Persona, team member Role Worker, stakeholder
Activity (with steps) n/a (not plan-driven, backlog item types come close) Task (with steps) RUP: activity, OpenUP: task
Artifact No direct pendant (template? documentation?) Work product UP: artifact
Technique (part of activity description) Practice No direct pendant (tool comes close) UP: guidance, guideline

In short, activities describe work to be done, techniques (or practices) help doing so; more than one technique might support an activity. For instance, use case modeling and user story telling are two techniques to elicit functional requirements. Artifacts are deliverables of activities, templates suggest content and structure for them. For example, an architectural decision log (an artifact) may come as a Nygard Architecture Decision Record (ADR), as a Y-Statement, as a Tyree/Akerman table, etc. Techniques and tools support and/or partially automate the activities.

The above terms establish an ubiquitous language (or domain model) of service design and agile architecting — in the (bounded) context of this repository. 😉

Note: Method adoption is eased if you make your methods mighty.

Acknowledgments

The creation and release of DPR was partially supported by the project “Domain-Driven Digital Service Engineering” funded by the Hasler Foundation.

Contributors (input, technical writing, feedback):

Stefan Kapferer and Oliver Kopp reviewed selected repository content and structure. Many members of our professional networks provided input and/or inspiration through discussions, workshops, joint client projects and many other ways. Thank you!

Getting Involved

If you would like to help improve this collection of software/service/API design practices:

More information can be found here.

DPR Metadata

title: Design Practice Repository (DPR)
owner: Olaf Zimmermann (ZIO)
date: "01, 27, 2023"
copyright: Copyright 2020-2023 Olaf Zimmermann (unless noted otherwise). All rights reserved.

License

Creative Commons License
This work is licensed under a Creative Commons Attribution 4.0 International License.