Documenting systems without drawing boxes
As a Cloud Engineer, I’ve rotated through 8 short-term roles in the last 7 years.
When I start a role, I ask where the documentation is, and this question is usually met with some slightly sheepish grins. Where there has been an emphasis on getting into production, documentation is usually incomplete, if not absent entirely.
Atlassian’s Confluence can work well, as can simple Markdown documents in a version control system. Even Word documents in a folder, well-maintained are useful. Other than screenshots, most documents lack good diagrams.
For technical diagrams, most IT teams still like Visio (if licensed for the whole team), or Visio-like systems such as diagrams.net (formerly draw.io) or lucidchart.com, or even PowerPoint.
Other than “where should we store the source document?”, my main frustration with these “box-like” systems is when adding a new item with a longer description, either having to update the size of other boxes to match, or group and move many boxes around the screen.
Staying within Markdown as a format, I liked Mermaid to “create diagrams using text”, but in the last couple of weeks I’ve started to appreciate Structurizr which can “create multiple diagrams from a single model”. It uses the C4 model which I hadn’t come across before, but even just with Context and Container, I’ve been quickly able to generate some useful diagrams, and crucially, rework them as I’ve realised additional details. And I haven’t had to line up any boxes, just simply refresh. Exporting to PlantUML and image formats took some more effort, but I’ll write about those soon.
Are you using any “diagrams as code” tools?