Download the slides here DDD 2022 Slides
About Me
Currently
- Principal Consultant & Practice Director SixPivot
- Technology Director Hey Lemonade
Previously
- Various Enterprise, Startup and Freelance
| SixPivot | Hey Lemonade |
|---|---|
|
|
Why do we document things?
- Communicate complex systems easier
- Reduce cognitive load
- Developer On-boarding
- Software and Solution Architecture
- Architectural Guidelines and Principles
- Decisions and rationale
- Disaster recovery
Why DON’T we document things?
- Documentation is boring
- Often requires special tooling, or licenses
- Diagramming tools are often hard to version control
- Perfect is the enemy of done
Traditional approach
Documentation Tools
- Wikis, Confluence
- Word Documents
- Specialised tools
Illustration Tools
- Visio
- Draw.io
- Paint
My ethos about documentation?
A possible solution?
- Be pragmatic
- Adopt “Documentation as Code”
- Favour the separation of structure from presentation
- Minimal requirement for extra tooling
Pros and cons
Pros
- Version controllable / diffable
- Simple to use/learn
- Using a DSL vs just diagrams means there is context
- Cross-platform
- Minimal tooling
- Can generate images / pdf / ppt
- Minimal licensing
Cons
- Downside is the learning curve
- Code sprawl
- Harder to search & aggregate
- Less accessible to non-tech folk
- PlantUml isn’t supported in all markdown flavours
Markdown Readmes
- A quick intro for onboarding
- Use a template for consistency
- Google for examples
- Customise for your organization
https://github.com/kefranabg/readme-md-generator
Architectural Guidance
- Architecture Principles
- Assumptions
- Make it easier for developers to make decisions
- Could this meeting have been a Principle?
Well-defined principles
- Name: Succinct, easy to remember, and carries the essence of the rule (few words)
- Statement: Unambiguous statement defining the rule (1 to 3 sentences)
- Rationale: Why is this rule important, particularly in terms of business benefits.
- Implications: Identifies explicitly how the rule affects the business, teams, etc.
Tracking Decisions
- Markdown Decision Records (MADR)
- Context/Problem
- Considered Options
- Decision
- Consequences
- Markdown Decision Records (MADR)
- Context/Problem
- Considered Options
- Decision
- Consequences
- Markdown Decision Records (MADR)
- Context/Problem
- Considered Options
- Decision
- Consequences
Diagramming - PlantUML
- Text-based diagramming
- Support for multiple diagram types
- Sequence diagram
- Class diagram
- Activity diagram
- Entity Relationship diagram
- Extensible with Libraries
- Azure, Kubernetes, AWS, C4
- Tooling
- Visual Studio Code & Extensions
- Supported by JetBrains and others also
- Supported in various Markdown wikis
https://crashedmind.github.io/PlantUMLHitchhikersGuide/
https://github.com/plantuml/plantuml-stdlib
PlantUML Demo
Sequence Diagram
Entity Relationship Diagram
C4 Model
- Created by Simon Brown (see YOW 2022)
- Helps avoid overly-complex diagrams
- Context (level 1): system scope, users and other systems
- Container (level 2): represents an application or a data store
- web application, mobile app, serverless function, embedded device
- Component (level 3): internals of a container
- Code (level 4): class-level decomposition
https://adrianvlupu.github.io/C4-Builder/
https://github.com/plantuml-stdlib/C4-PlantUML
C4 Model Demo
Bad Context Diagram
Good Context Diagram
C4 Model & Markdown Demo
Context & Container Diagrams
Bringing it all together
- Roll your own scripts
- Markdown front-matter for metadata
- Output to PDF in CI/CD pipelines
- Tools like C4 Builder
https://adrianvlupu.github.io/C4-Builder/
Structurizr
- Tooling to extend on PlantUML & C4 & ADRs
- More control over rendering
- Linking between different elements
- Model and element reuse
- Team sharing
- (Also by Simon Brown)
https://structurizr.com/help/decision-log
How do you encourage developers to document their code inline? So that code doco can be rendered in the build pipeline.
It’s not something I actively encourage, but it depends on the type of software you’re writing. As with most of the stuff I’ve presented here, be pragmatic.
Through the pull request process is a good way to ensure that code is documented, if required. I would suggest documenting code inline if the intent of the code can’t be clearly understood by a mid-level developer.
However, if you’re creating a library or API that is to be consumed by 3rd parties, then inline documentation might be more useful. In this case I’d look at using convention tests or some other process in your CI build to break the build if a developer adds new code without the expected documentation.
Can you recommend a good starting template for an Architectural Guidance doc?
Software Architecture for Developers – Simon Brown http://leanpub.com/software-architecture-for-developers
Creating Software with Modern Diagramming –Ashley Peacockhttps://pragprog.com/titles/apdiag/creating-software-with-modern-diagramming-techniques/
As much as I would hate to recommend TOGAF… https://pubs.opengroup.org/architecture/togaf8-doc/arch/chap29.html
Any alternatives to PlantUML? Have you looked at mermaid?
Yep, I’ve used mermaid. It’s a good option because it seems to be natively supported by more wikis and github etc.
The reason I didn’t talk about mermaid much is because it’s a bit limited in functionality compared to PlantUML. Having said that, if it’s supported by your platforms then mermaid is a good option. It’s also relatively straight forward to move from mermaid to PlantUML later if you need the extended functionality.
From a documentation point of view, a couple of people suggested Asciidoc during the Q&A session. I haven’t looked into this heavily, but I think it’s worth a look as well, especially for creating large-scale user documentation.
Another project I recently came across is kroki.io – it seems to be an amalgamation of a bunch of other text based documentation projects.
After the DDD presentation, Daniel Mackay actually reached out to me about a couple of blog posts he’s recently done on this topic that are worth a read:
- https://www.dandoescode.com/blog/plantuml-vs-mermaid/
- https://www.dandoescode.com/blog/c4-models-with-structurizr/
Any tools for exporting tables from Excel to markdown?
There’s actually a Visual Studio Code extension for that. If you just want to copy/paste tables this is a good option:
https://marketplace.visualstudio.com/items?itemName=csholmq.excel-to-markdown-table
I’m not sure about what you’d do if you wanted to extract a table as part of a CI process though.
What would you recommend for BPMN?
Good question. I haven’t done a lot with BPMN.
When I did have to view some BPMN documents recently I used Visual Studio Code plugin to visualise the diagrams, but that’s about the extent of my experience unfortunately.
I know PlantUML doesn’t currently support it because there’s an open issue discussing this.
Can you do cloud infrastructure diagram? Also, can you add images (logos)?
Absolutely. There are a ton of PlantUML libraries for this: