Developer-friendly documentation
Most developers don’t like writing documentation. It’s tedious work and it easily becomes outdated - and wrong documentation is even worse than none at all. Keeping the docs up to date can be a challenge though, especially if there are charts or diagrams involved.
Renamed something? Added a new component? Forgot a part? Chances are you’ll need to spend a considerable amount of time recreating your charts, moving arrows and boxes around and making sure everything is aligned again.
A very common diagram type in software documentation are sequence diagrams, and we recently discovered a great tool for drawing writing them. That’s right, https://websequencediagrams.com allows you to “program” your diagrams in a simple domain specific language. You provide the objects and their interactions as source code, and the tool renders the diagram and takes care of alignment, margins, arrow lenghts and so on. Let’s look at an example:
Client->API: Request
This renders the following diagram:
Let’s add a response arrow:
Client->API: Request
API-->Client: Response
Notice how the arrow with two dashes (-->) is rendered as a dashed arrow.
There are ready-to-use snippets for more complicated elements like alternatives, loops and so on. One last example:
Client->API: Request
alt invalid token
API-->Client: Unauthorized
else valid token
API->+Database: Query
Database-->-API: Result
API-->Client: OK
end
Creating sequence diagrams like this has many advantages:
- It is a lot faster (you can focus on the content instead of the layout).
- It is very maintainable. Want to rename a component? No problem!
- You can check in the source code of your diagrams to your version control system.
- Most importantly, it is actually fun to create documentation that way.
As a bonus, you get shareable links to the diagrams (like we used here), you can choose between different styles (see below) and there’s even an API - what more could you ask for?