Appendix D: Table of Tips
Here you find an overview of all tips contained in this book. The following table is generated9 from the complete book by parsing the markdown source.
| ID/Link | Tips |
|---|---|
| Tip III-1 | Appoint a Responsible Person (The Docu-Gardener) |
| Tip III-2 | Document economically (“Less is often more”) |
| Tip III-3 | Clarify appropriateness and needs through early feedback |
| Tip III-4 | Communicate top-down, work differently if necessary |
| Tip III-5 | Focus on Explanation and Rationale, Not Only Facts |
| Tip III-6 | Rate Requirements Higher than Principles |
| Tip III-7 | Separate Volatile and Stable Documentation |
| Tip III-8 | Don’t Repeat Yourself, If Possible |
| Tip III-9 | Document Unmistakably |
| Tip III-10 | Establish a Positive Documentation Culture |
| Tip III-11 | Create Documentation From The Reader’s Point of View |
| Tip IV-128 | Keep the introduction (arc42 section 1) brief |
| Tip IV-129 | Document and explain the specific quality tree |
| Tip IV-130 | Document the quality tree as mindmap |
| Tip IV-131 | Use the quality tree as checklist |
| Tip IV-132 | Consider usage-scenarios in the quality tree |
| Tip IV-133 | Consider change-scenarios in the quality tree |
| Tip IV-134 | Consider stress- and error scenarios in the quality tree |
| Tip IV-135 | Use the quality tree for systematic architecture assessment/evaluation |
| Tip IV-136 | Search for risks with different stakeholders |
| Tip IV-137 | Examine external interfaces for risks |
| Tip IV-138 | Identify risks by qualitative architecture evaluation |
| Tip IV-139 | Examine (development/deployment/etc) processes for risks |
| Tip IV-140 | Take the glossary seriously |
| Tip IV-141 | Document the glossary as a table |
| Tip IV-142 | Keep the glossary brief and compact |
| Tip IV-143 | Restrict the glossary to relevant terms, avoid trivia |
| Tip IV-144 | Make the product owner be responsible for the glossary |
| Tip IV-1 | Compact summary of the functional requirements and driving forces. |
| Tip IV-2 | Limit yourself to the essential tasks and use cases |
| Tip IV-3 | Highlight the business objectives of the system |
| Tip IV-4 | Create an overview by grouping or clustering requirements |
| Tip IV-5 | Make sure you can reference the requirements |
| Tip IV-6 | Use activity diagrams to describe functional requirements |
| Tip IV-7 | Use BPMN diagrams to describe functional requirements |
| Tip IV-8 | Use a numbered list to describe functional requirements |
| Tip IV-9 | Use (semi) formal text to describe functional requirements |
| Tip IV-11 | Always work with explicit quality requirements |
| Tip IV-12 | Explain quality requirements through scenarios |
| Tip IV-13 | If you do not get quality requirements, make your assumptions explicit |
| Tip IV-14 | Use checklists for quality requirements |
| Tip IV-15 | Use examples to work out quality goals together with your stakeholders |
| Tip IV-16 | Keep the introduction short! Show only the “hit list” of the quality requirements |
| Tip IV-17 | Combine quality goals with the action points of the “solutions strategy” section |
| Tip IV-18 | Show the detailed quality requirements in arc42 section 10 |
| Tip IV-19 | Search broadly for stakeholders |
| Tip IV-20 | Describe the expectations of the architecture and documentation stakeholders |
| Tip IV-21 | Maintain a stakeholder table |
| Tip IV-22 | Do not use the stakeholder table if your management already maintains a consistent stakeholder overview |
| Tip IV-23 | Classify your stakeholders by interest and influence |
| Tip IV-24 | Look at the contraints of other systems within the organization |
| Tip IV-25 | Clarify the consequences of constraints |
| Tip IV-26 | Describe organizational constraints |
| Tip IV-27 | Describe design and development constraints |
| Tip IV-28 | Differentiate different categories of constraints |
| Tip IV-29 | Explicitly demarcate your system from its environment |
| Tip IV-30 | Show the context graphically |
| Tip IV-31 | Combine the context diagram with a table |
| Tip IV-32 | Explicitly indicate risks in the context |
| Tip IV-33 | The context should give an overview and should not contain any details |
| Tip IV-34 | Simplify the context boundary through categorization |
| Tip IV-35 | If many external systems are involved, merge them by explicit criteria |
| Tip IV-36 | Summarize “many external systems” with ports |
| Tip IV-37 | Show all (all!) external interfaces |
| Tip IV-38 | If you offer external interfaces to other systems, create discrete interface documents |
| Tip IV-39 | Differentiate domain and technical context |
| Tip IV-40 | Show rather data flows within the domain context |
| Tip IV-41 | Show external influences in the context |
| Tip IV-42 | Read Douglas Adams |
| Tip IV-43 | Show transitive dependencies in the context |
| Tip IV-44 | Pay attention to quality requirements for interfaces |
| Tip IV-45 | Show the technical context |
| Tip IV-46 | Use the technical context to describe protocols or channels |
| Tip IV-47 | Explain the relationship between a functional interface and its technical realization |
| Tip IV-48 | Show the technical context in the deployment view |
| Tip IV-49 | Show variants of the technical context |
| Tip IV-50 | Explain the solution strategy as compact as possible (e.g. as list of keywords) |
| Tip IV-51 | Describe important solution approaches as a table |
| Tip IV-52 | Describe solution approaches in context of quality requirements |
| Tip IV-53 | Refer to concepts, views or code |
| Tip IV-54 | Let the solution strategy grow iteratively / incrementally |
| Tip IV-55 | Justify the solution strategy |
| Tip IV-56 | Use a common format for sections of the building block view |
| Tip IV-57 | Organize the building block view hierarchically |
| Tip IV-58 | Always describe level-1 of the building block view (“Level-1 is your friend”) |
| Tip IV-59 | Describe the responsibility or purpose of every (important) building block |
| Tip IV-60 | Hide the inner workings of blackboxes |
| Tip IV-61 | Document blackboxes as table using the minimal blackbox template |
| Tip IV-62 | Document blackboxes with the extensive blackbox template |
| Tip IV-63 | Document blackboxes as structured text |
| Tip IV-64 | Justify every whitebox (blackbox decomposition) |
| Tip IV-65 | Document whiteboxes with the minimal whitebox template |
| Tip IV-66 | Document whiteboxes with the extensive blackbox template |
| Tip IV-67 | Use runtime views to explain or specify whiteboxes |
| Tip IV-68 | Use inheritance to describe similar behavior of multiple building blocks |
| Tip IV-69 | Use crosscutting concepts to describe or specify of multiple building blocks |
| Tip IV-70 | Document multiple levels of the building block view |
| Tip IV-71 | Keep your external interfaces in context and building block view consistent |
| Tip IV-72 | Explain the mapping of source code to building blocks |
| Tip IV-73 | Describe where to find the source code of building blocks |
| Tip IV-74 | Organize the mapping of source code to building blocks according to directory structure |
| Tip IV-75 | Organize the mapping of source code to building blocks according to the modularization of the programming language(s) |
| Tip IV-76 | Ensure that every piece of source code has its proper place within the building block view |
| Tip IV-77 | In exceptional cases, include thirt-party software (libraries, frameworks, middleware etc) in the building block view |
| Tip IV-78 | Frugally document internal interfaces |
| Tip IV-79 | Document / specify interfaces with unit-tests |
| Tip IV-80 | Document / specify interfaces with runtime scenarios |
| Tip IV-81 | Use building block view level-1 for “further” information |
| Tip IV-82 | Refine several building blocks at once, if that’s adequate |
| Tip IV-83 | If you refine several building blocks at once, ensure uniqe mapping |
| Tip IV-84 | Refine only a few building blocks |
| Tip IV-85 | Document concepts instead of building blocks |
| Tip IV-86 | Always map existing building blocks to the activities within runtime scenarios |
| Tip IV-87 | Limit the runtime view to very few scenarios |
| Tip IV-88 | Explain schematic (generic) processes in the runtime view |
| Tip IV-89 | Explain concrete (specific) |
| Tip IV-90 | Use runtime scenarios primarily to detect or identify building blocks - rarely for documentation |
| Tip IV-91 | Use sequence diagrams to describe or specify runtime scenarios |
| Tip IV-92 | Document or specify parial scenarios |
| Tip IV-93 | Use plain activity diagrams to describe or specify runtime scenarios |
| Tip IV-94 | Use activity diagrams with partitions to describe or specify runtime scenarios |
| Tip IV-95 | Use text to describe runtime scenarios |
| Tip IV-96 | Mix large and small building blocks within single runtime scenarios |
| Tip IV-97 | Document or specify the technical (hardware) infrastructure |
| Tip IV-98 | Document and explain the infrastructure decisions |
| Tip IV-99 | Document or specify the various (technical) runtime or staging environments |
| Tip IV-100 | Show the deployment view as hierarchy |
| Tip IV-101 | Document or specify the mapping of building blocks to hardware |
| Tip IV-102 | Use UML deployment diagrams for software-hardware-mapping |
| Tip IV-103 | Use building blocks instead of artifacts in deployment diagrams |
| Tip IV-104 | Use artifacts instead of building blocks in deployment diagrams |
| Tip IV-105 | Use tables to document or specify software-hardware mapping |
| Tip IV-106 | Explain intention or relevance of infrastructure nodes |
| Tip IV-107 | Document or specify everything which might be neccessary for operating the system |
| Tip IV-108 | Leave hardware decisions to infrastructure experts |
| Tip IV-109 | Restrict documentation of concepts to the most important topics |
| Tip IV-110 | In concepts, explain “how it should be done” |
| Tip IV-111 | Keep foundations of background information to a bare minmum |
| Tip IV-112 | Document or specify domain or business models |
| Tip IV-113 | Combine domain models with the glossary |
| Tip IV-114 | Document or specify the domain model |
| Tip IV-115 | Create at least a domain data model |
| Tip IV-116 | Document concepts by showing source code |
| Tip IV-117 | Document crosscutting concepts with the 4-quadrant-model |
| Tip IV-118 | Document decisions instead of concepts |
| Tip IV-119 | Use stereotypes to document which concepts are applied within which building blocks. |
| Tip IV-120 | Use the arc42 topic proposals as checklist for crosscutting concepts |
| Tip IV-121 | Document the criteria for important decisions |
| Tip IV-122 | Explain reasons for important decisions |
| Tip IV-123 | Document or explain decisions as mindmap |
| Tip IV-124 | Document or explain decisions as table |
| Tip IV-125 | Document or explain decisions as “Architecture Decitions Record (ADR)” |
| Tip IV-126 | Document or explain discarded alternatives |
| Tip IV-127 | Document or explain decisions informally as blog |
| Tip V-1 | Explicitely clarify the target audience of your documentation |
| Tip V-2 | Use existing examples as jumpstart |
| Tip V-3 | Remove unneeded arc42-sections |
| Tip V-4 | Augment arc42 by required sections or topics |
| Tip V-5 | Indicate currently unneeded arc42 sections |
| Tip V-6 | Prepare an arc42 repository for the team |
| Tip V-7 | Prepare a sandbox for documentation |
| Tip V-8 | Document (and work) from different perspectives |
| Tip V-9 | Documents belong into version control |
| Tip V-10 | Conduct brief and thematically focussed documentation reviews |
| Tip V-11 | Treat documentation tasks equal to developent tasks |
| Tip V-12 | Document continously - parallel to development |
| Tip V-13 | Always document in timeboxes |
| Tip V-14 | Formulate like “The system {has|does|is|…}” |
| Tip V-15 | Create hindsight documentation iteratively in short timeboxes |
| Tip V-16 | Create documentation before you continue development |
| Tip V-17 | Document those parts you’re anyhow working on |
| Tip V-18 | Make other documents unnecessary as quickly as possible |
| Tip V-19 | Remove superfluous or outdated documents |
| Tip V-20 | Explicitly reveal problems and risks |
| Tip V-21 | Start with the (business) domain |
| Tip V-22 | Start with quality requirements |
| Tip V-23 | Start with the context and external interfaces |
| Tip V-24 | Start with the solution strategy |
| Tip V-25 | Take documentation serious even in agile projects |
| Tip V-26 | Make documentation part of the Definition-of-Done |
| Tip V-27 | Apply an iterative and incremental approach to documentation |
| Tip V-28 | Use walls instead of electronic tools |
| Tip V-29 | Enable cooperative work, even for distributed teams |
| Tip V-30 | Modularize extensive documentation |
| Tip V-31 | Extract goals, context and concepts |
| Tip V-32 | Appoint a responsible person responsible for the overall documentation |
| Tip V-33 | Unify the documentation toolchain |
| Tip V-34 | Leave documentation of IT-landscape to enterprise architects |
| Tip V-35 | Structure your overall documentation along organizational boundaries |
| Tip II-1 | Improve your arc42 skills by reading additional examples |