| Is | Is _not_ | |---|---| | A template for architectural documentation | An architecture | | Easy to read / accessible | A modelling tool | | A "pit of success" | A silver bullet for documentation |

- As much or as little as it makes sense - Easy to use - Meant to be adapted to current context

| Do's | Don't | |---|---| | Provide context | Don't skip this | | Cover the important bits | Avoid going into details | | Use diagrams | Don't make this too long | | Use concrete examples | | - Focus on this section - Use diagrams to succintly describe and and give context - Examples are easy to understand - Also examples \ scenarios can very clearly convey quality requirements

- External constraints refers to ability to hire talent, maturity of constrained tooling, anything impacting scale, etc - Technical includes existing or available skillset, having to use a tool or platform due to agreements etc. Do's and dont's - Use small tables to present and explain - Explain consequences of breaking a constraint. Sometimes you may prefer to do so, but note the consequences. - Don't ignore organizational and political constraints

- An overview of the ecosystem -> where the sytem we're building lives, with it's neighbours: who drives it, - I _love_ this section - Normally split into two sections: business context and technical context - At least tech context is a DIAGRAM-heavy section - Wardley maps in business context + C4 System level and business model canvas may just be enough - Focus on public interfaces for system context. - Avoid too much detail -> This is an overview. The other sections will expand and link back - Again: show data flow - this is useful for some non-techy, but tech-related stakeholders.

Since this section is about context and understanding how it's used, add following (if they exist) to provide context: - User story mapping - Use Example mapping diagrams - Use Domain story-telling

- All important decisions MUST be documented here - none missing - Analysis, design, hosting, (internal and external) integration, data, all should be reflected if possible and make sense - Link to next sections - Don't get carried away. This is not an ADR list -> that's section 9 :)

- Avoid zooming into all services - A tree view where system is zoomed in to C4 containers \ Logical services - C4 containers are zoomed in to C4 components -> pieces of logic which sit inside the same process - Potentially zoom components into code (which is level 3), but avoid unless really necessary due to cost of maintenance - Absolutely use diagrams! - Use tables to describe black boxes which you don't zoom into - Use some text to explain purpose

- Avoid zooming into all services - A tree view where system is zoomed in to C4 containers \ Logical services - C4 containers are zoomed in to C4 components -> pieces of logic which sit inside the same process - Potentially zoom components into code (which is level 3), but avoid unless really necessary due to cost of maintenance - Absolutely use diagrams! - Use tables to describe black boxes which you don't zoom into - Use some text to explain purpose

- Clearly define bounded context. Better yet align your diagrams with your bounded contexts - Bounded context canvas will be replacing the text describing the blackboxes at different levels. Maybe do this? - Aggregate design canvas maybe a reasonable addition for a level 3 (a zoom on components to show code)

- Dynamic diagrams in the sense of UML dynamic diagrams: - Sequence diagrams - Activity diagrams - Don't try to be thorough! Focus on the important ones. It can be a huge productivity drain to maintain. - Diagrams! Diagrams! - Link to the building blocks view parts which are participating - Do not underestimate the ability of dynamic aspect documentation to convey behaviour and context. This is a very important bit of the architecture.

- Use multiple levels in these documentation - Document various environments - Link decisions about hardware to quality goals

- Concepts as in "conceptual integrity", think uniformity and cohesion of practices. Hence pattern language - Stuff to put here: + Architectural patterns + Tech decisions + Metadata use + Shared processes - Only the important ones

- Don't do unexpected things! - Don't run the risk of moving to another part of the system, and brake stuff due to muscle memory - Productivity across code that adheres to the conceptual integrity

- This is a section to document your _important_ ADR's... - ...but it's not an ADR record. Use something else for that. Carefuly consider which ADR's belong here - If you can document the decision near the effect it has on the different sections, prefer to do so. Cause and effect make sense together. - Only exception: the important \ expensive bits. You will probably want to go deeper into some decisions and this breaks the benefit of having cause-effect in the different architectural views. - Things to write: + Provide context + Explain cost + Alternatives considered + Explain decision

- A place for all qualiry requirements which didn't make the cut for section 1.2 - Link quality with stakeholders. - Quality requirements are very important for architecture - Quality tree gives an overview. It has a basic structure, but takes the shape of a mind map. Good option to give an overview, but probably safe to skip and focus on scenarios, unless you have a lot of requirements from different SME's \ stakeholders - Useful as a checklist to validate architecture (hence maybe the place in the template??)

- Link with stakeholders

- This is an important bit (especially for DDD'ers) - (obviously) Be specific about the term used - Explain expectations of seeing the terms in code (classes, structures, variables, processes, etc)

- There are things which are useful in DDD, which arc42 does not specifically cater for - Regardless they are orthogonal concerns and can be used together nicely - I already made some suggestions for extending to include artifacts one expects from analysis using DDD