Home About README

Documentation for Developers

December 04, 2022

Download the slides here DDD 2022 Slides

About Me

Currently

Previously

  • Various Enterprise, Startup and Freelance
SixPivot Hey Lemonade
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

DDD202226

  • A quick intro for onboarding
  • Use a template for consistency
  • Google for examples
  • Customise for your organization

readme-md-generator

https://github.com/kefranabg/readme-md-generator

DDD202227

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.

DDD202228

Tracking Decisions

DDD202229

DDD202230

DDD202231

DDD202232

DDD202233

DDD202234

DDD202235

Diagramming - PlantUML

DDD202236

  • 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://plantuml.com/

https://crashedmind.github.io/PlantUMLHitchhikersGuide/

https://github.com/plantuml/plantuml-stdlib

DDD202237

PlantUML Demo

Sequence Diagram

DDD202238

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://c4model.com/

https://adrianvlupu.github.io/C4-Builder/

https://github.com/plantuml-stdlib/C4-PlantUML

https://c4model.com/review/

DDD202239

C4 Model Demo

Bad Context Diagram

DDD202240

Good Context Diagram

DDD202241

C4 Model & Markdown Demo

Context & Container Diagrams

Bringing it all together

DDD202242

  • 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/

https://pandoc.org/

Structurizr

DDD202243

  • 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.org/

https://structurizr.com/

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:

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: