- Published on
I like to work in pictures - and I use diagrams A LOT as a way to express the problem or solution in a digestible format. A picture is worth a thousand words, after all!
In the early stages of understanding, I find it's best to stay in a diagramming tool like "draw.io" - you can quickly throw things onto a page, often in real-time while collaborating on a screen share and let the diagram drive the narrative of the conversation. The outputs of these diagrams can be easily shared for all to see and can quickly build up a dossier of useful documentation when it comes to explaining or coding the solution down the line.
I tend not to worry so much at this stage about following any particular "style" of diagram, with draw.io supporting everything from swim lanes, flow charts, deployment diagrams, component diagrams and more, I usually go for whatever combination is the most useful or informative for the situation. The important measure for a diagram is that everyone, who needs to, can understand it.
As you get closer to an agreed architecture, there comes a point where it's worth moving to a "model" over a "diagram" (by that I mean not just pictures, but written syntax that can be output as diagrams - i.e. "documentation as code"). What springs to mind here is PlantUML (or Mermaid diagrams) which allow you to define a plethora of diagram types using written syntax. The main benefit of this in my experience is change control, as written syntax plays very nicely with source control systems, such as Git so you can request peer reviews of documentation changes, keep it aligned with code changes and can see the history of changes with commit messages as to why things changed.
As a "standard" set of diagrams to get started, I'd recommend the "C4 Model" - this will give you a good repeatable basis for capturing the system architecture at various levels of abstraction. I don't really recommend going beyond components and even then, I'd use that level of detail sparingly. However, both PlantUML and Mermaid support multiple other diagram types so it's worth having a dig through to see what you find useful. I especially like to create sequence diagrams as text, as I find that easier than doing it graphically. You can even graphically represent JSON or YAML data, create pie charts and more!
I tend to categorise documentation into "specific" or "overarching" - "specific" documentation you'd find in the Git repo of the specific system it relates to, typically in a "/docs" folder alongside "/src" and here you will find the software and solution level documentation focused on the internal workings of this system, with perhaps minimal references to the external systems it interacts with (e.g. at the "context" level). Some good examples would be the lower level C4 diagrams, sequence or flow diagrams etc. Sometimes though, documentation focuses on the interaction between systems rather than a specific system, or it's documenting the business processes using mind maps etc. and isn't "about" any particular API. In that case to me that's "overarching" documentation and I'd have a dedicated repo for that genre of documentation.
Unitl recently, I was using an open source tool called "C4Builder" to manage my documentation projects. It allows you to setup a structure of "md" (markdown) and "puml" (plantUML) files and then generate them into a HTML/Image output, which can be hosted directly in the Git repository. There are plugins for VS Code and JetBrains Rider that allow you to code Markdown/PlantUML with previews, while you are working on the documentation, which c4builder can then "compile". However, this tool seems to no longer be maintained so it doesn't support the latest version of PlantUML which limits what diagrams and syntax are available to you - I have created a Docker image version that monkey patches in the latest (at the time of writing) PlantUML so you can at least continue to build .c4builder projects, but I've now discovered a new way to manage my documenation: JetBrains Writerside.
Writerside is still in EAP and has just announced support for PlantUML, it already supports Mermaid diagrams and has a tonne of other useful features for creating and publishing technical documentation, such as supporting OpenAPI specs and markup/markdown elements so it's well worth a look!
To sum up, I recommend creating diagrams throughout the software development process, including during requirements gathering to visualise and get a collective understanding of the problem and agreement on proposed solution(s). As you move towards starting to write code, formalise the necessary (not everything) documentation into a syntactic model that is peer reviewed and source controlled. Store this either alongside the code, or in an "overarching" architecture repository. Ensure your CI/CD process automatically publishes the latest documentation when it changes. Finally, make sure the documentation you are creating has a purpose and stays up to date, if it's old or no longer serves a purpose - archive it!
Data Fetching: Incremental Static Regeneration | Next.js