Documenting systems — Some thoughts



  • Code moves fast.
    Engineers are conditioned to utilize modern source control systems and deploy in a CI/CD environment.
    The documentation tooling and environment must support this and be compatible.
  • Use as similar toolset as possible.
    This is a corollary of the above.
    Documentation is something to be done by the engineers themselves.
    If you prefer a cheesier quote, the people “making history” should be the ones writing it first hand.
    Context switching takes time, a different tool is a potential barrier to entry.
    Engineers are system and process users as well, so the goal is to reduce friction as much as possible.
  • Be as close to the codebase as possible.
    Another corollary.
    The furthest the docs are from the code, the harder it is to keep them in sync.
    Deep-linking and creating references to modules and classes, becomes increasingly harder with physical distance.
  • How much to document?
    I personally view system documentation a little bit like the sea: readily accessible to everyone.
    Everyone should be able to dip their toes in and appreciate Awww! How poetic!. Just as the sea, docs must be accessible, transparent and accessible. Up to a depth.
    After that, it is only for experts, most possibly using different tooling than everyone else.
  • Opinions?
    Creating documentation is inherently a collaborative effort.
    It is impossible to fit everything in a person’s head without error.
    The tooling and process should facilitate and encourage collaborative editing.


  • the sequence of important decisions which lead us to the present state, and
  • the present state, in an as clear way as possible.

The course so far

  • What problem / issue had to be addressed
  • Which was the chosen solution / system
  • When was the decision taken / implemented
  • Why it was chosen i.e. what restrictions/requirements/assumptions weighed in on the decision

Telling the story of now


Drilling down

  • Context
    At the top-most level users/actors interact with “systems”.
    A system is a black box which offers a related set of functionality to its actors (“offers value” in C4 parlance). This is from a user’s point-of-view, so it might be a little subjective.
  • Container
    Next level of abstraction, Containers live inside systems.
    They are something into which code “runs” or data “lives” (Kubernetes cluster, Postgres DB, HTML 5 app, AWS S3 buckets,…).
    This is where the “logical” architecture intersects with the “physical”.
    Containers can be marked/annotated with the characteristics of the actual deployment (2 node cluster,, 6 worker pool,…).
  • Components
    According to C4, Components are
  • and Classes
    The last level of detail should need no further introduction.


Visio and MS Word

Google docs

  • Accessibility of information
    All documents start their life in the user’s personal Google drive, so it takes additional steps (and team discipline) to move them to a shared structure.
    And as with all things shared, there is the question of the folder structure itself.
    How should it be organized? Per team? Per system? Otherwise?
    Retrieving information from an archive of Google docs is another challenge.
    Google’s search and machine learning functionality is meant to ease the location of important documents.
    This results in a mix of immediate “hits” for the 95th percentile of searches and quite some time spent looking for the remaining 5%.
  • Privacy of information
    Being an internet-first offering, means that mistakes in GSuite are immediately visible.
    Anyone who has edited a Google doc, quickly finds out that making a mistake in the sharing settings makes the document accessible to anyone on the internet.
    In the enterprise Google offering this is less of an issue, but requires careful locking down from the admins and discipline from the users.



…and AsciiFlow

…and mermaidJS

…and LucidChart

Parting thought




Life-long learner, happy father, trying to do some software engineering on the side.

Love podcasts or audiobooks? Learn on the go with our new app.

Recommended from Medium

Kafka Exceptions: Building resilience into the system

Why Do We Need Code and Functional Coverage

fancy graphic of a chip placed on a PCB

Why study Software Engineering?

Monads in Elm

Witchcraft: the magic of math, functional programming, and community

Summarizing Agile

Testing Perl: To plan or not to plan

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Stelios Gerogiannakis

Stelios Gerogiannakis

Life-long learner, happy father, trying to do some software engineering on the side.

More from Medium

Why You Should Stop Comparing Candidates When Hiring

I’m #Hiring! A Comedy of Errors

A cute pomeranian with black plastic-frame glasses and a maroon sweater sits attentively in front of a tablet

Yet another chapter story

Yet another chapter story

[Book] The Art of Impossible: A Peak Performance Primer