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

DPR: Artifacts and Templates for Them

Context and Motivation

Checklists and templates can speed up the creation of artifacts, and help ensure their quality. They also promote a common language among designers, reviewers, managers, and other design stakeholders. These goals can only be achieved if the checklist, templates, and any other artifacts are grounded in practice and engineered with a “less is more” spirit, following the first law of method engineering and adoptions established in the activities overview: “if in doubt, leave it out”.

The Agile Alliance lists more than 100 agile practices and concepts in its Agile Glossary. Selecting and applying them well requires experience, training, and/or consultancy. On the other end of the spectrum, more traditional plan-driven methods tend to impose processes on teams, which is not always appropriate and often not received well. Parts of the agile community see methods as “training wheels” only.

What is different in DPR?

We employ a best-of-both-worlds approach here: This artifact-templates folder collects commonly created artifacts and proven templates for them, the activities folder suggests (but does not norm) a light process through the creation of these artifacts by one or more of these roles. Feel free to deviate from it, and do not forget the second rule of method adoption:

Do not follow templates blindly, but adopt them to your needs (or: no cargo cult please).

Never fill out a template just because. If you cannot think of a benefit for a particular reader, skip its creation (and remember why).

Artifact and Template Overview

Specific to API/Service Design

Object-Oriented Analysis and Design (OOAD) and Domain-Driven Design (DDD) are particularly relevant for API and service design:

• DDD Context Maps as outcome of Strategic DDD (FAST Bounded Contexts)
• Domain Model (analysis level) as outcome of Tactic DDD
• More elaborated Domain Model (design level), also an outcome of Tactic DDD

The service/API design-specific artifacts/templates in DPR are:

• Candidate Endpoint List
• Refined Endpoint List
• API Description, a.k.a. business and technical service contract (captured as a API Description pattern) in the Microservice API Patterns (MAP) language
• Service Level Agreement (also a pattern in MAP)

General Software Engineering/Software Architecture

Requirements analysis and conversation with stakeholders can be captured in the form of:

• User Stories
• Use Cases
• Quality Attribute Scenarios (QAS) and other templates for NFR/QA elicitation
• System Context Diagram (SCD)

(Architecture) design work is usually documented both textually and visually:

• Architecture Overview Diagram (AOD) a.k.a. Container Diagram
• Component Diagram, providing a logical view on the architecture
• Component, Responsibility, Collaborations (CRC) cards
• Component Interaction Diagrams (CIDs), often expressed as UML sequence diagrams
• Integration flows (a.k.a. “Gregorgrams”)
• Deployment diagram (providing an operational, physical view)
• Y-Statements and other ADR formats
• Architectural refactoring template (from research project ARC)

Some evaluation and assessment templates are:

• Strength Weaknesses Opportunities Threats (SWOT) tables
• Architecture review report
• API/Code Review Checklist (futureWork)

DPR Metadata

title: "Design Practice Repository (DPR): Templates and Artifacts Overview"
author: Olaf Zimmermann (ZIO)
date: "01, 25, 2022 (Source: Project DD-DSE)"
copyright: Olaf Zimmermann, 2020-2023 (unless noted otherwise). All rights reserved.

License

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