I discovered C4 diagrams two years ago and I’ve been using them in my private projects since then. I use Confluence for all of my project documentation, so I’ve been using the draw.io add-on to make the diagrams because that’s the best solution I’ve found that lets me edit the diagrams inside of the document.
As I wrote in Towards a Portfolio Based Interview Process for Programmers, when describing what a GitHub portfolio repository should look like:
I could use an orientation. I need a starting place. The bigger the project, the harder it will be to jump in and take a look around. Give me what you’d give a new contributor.
The purpose of a context diagram is to explain the boundaries of your system. You do this by representing your system as a single box in the center and surrounding it with your various user roles and collaborating systems (see more on the C4 site).
To put one in a README, you could use mermaid’s C4 support for context diagrams. This support is experimental (in May 2023), so it’s very hard to get a good diagram. I am personally finding it impossible to get anything more than simple diagrams to look good enough.
To give an example, here is some code that I used to add a context diagram to the Page-o-Mat README (here’s a link to the commit in case I change it later).
C4Context %% This is a Mermaid diagram for the system context Person(designer, "Journal Designer") System(pageomat, "Page-o-Mat", "Makes Journal PDFs") Person_Ext(journaler, "Journal User") System_Ext(printservice, "Print Service", "A PDF printing service (e.g. LuLu).") Rel(designer, pageomat, "Creates specs for") Rel(pageomat, printservice, "Generates PDFs for") Rel(journaler, printservice, "Buys journals from") UpdateLayoutConfig($c4ShapeInRow="2", $c4BoundaryInRow="1") UpdateRelStyle(designer, pageomat, $offsetX="-40", $offsetY="40") UpdateRelStyle(journaler, printservice, $offsetX="-40", $offsetY="40")
It looks like this:
You can see that color is being used to indicate which parts of the entire system are in scope for the project.
If that’s too frustrating to use, then I suggest MonoDraw for making an ASCII Art version. The downside is that this diagram is hard to edit, but a context diagram doesn’t change much. Another small issue is that you can’t use color. I can live with just text tags (in
<<>>) for that because it saves me having to add more files to the repo for diagrams.