Skip to main content

DDD Melbourne

· 2 min read
Shaw Innes
Builder of things

Shaw at DDD Melbourne


I had the pleasure of presenting my thoughts about documentation as code, this time at DDD Melbourne.

The main point of this talk is to focus your documentation on filling the gaps between the obvious, how can you make your codebases easily discoverable and enable new team members to join your project and quickly get up to speed and provide valuable contributions in the shortest possible time.

Below is a quick visual outline of my presentation.

Visual overview of Documentation for Developers

  • Overview - README.MD Markdown files to help developers understand what they're looking at.
  • Get Started - README.MD Markdown file with more information to help developers get started, install dependencies, etc.
  • Old Decisions - Architecture Decision Records to understand what decisions have been made in the past, and why.
  • New Decisions - Architecture Principles to help guide future decisions.
  • Architecture - Diagrams to help developers understand the architecture of the system.
  • Sharing - Use mkdocs to to share documentation with the team.
  • Scaling - Ways to share and scale documentation as the team grows beyond a few repositories.


If you attended my DDD Melbourne talk, you can find the slides here.

Markdown README

Architecture Decision Records

Architecture Principles



C4 Model

Sharing Documentation

Scaling Documentation