Documentation for Developers
Onboarding new team members can be a costly aspect of building and maintaining software, and this gets harder the bigger your organisation gets.
It's well known how much we cringe at the thought of having to write documentation, but thinking about it differently, and adopting a documentation-as-code approach we can remove the friction of this process.
In my talk, "Documentation for Developers", I share some stories and practices you can use to help make your software easier to understand for new developers joining the team. I also share some tools and techniques for capturing the architecture and design of your software.
Whether you're a one-person team hoping to scale up, or an enterprise with hundreds of repos, this talk will have some useful tips.
.NET User Group Recording
DDD Brisbane 2022 Slides
Download the slides here DDD 2022 Slides
Audience Questions
The following questions were asked on the sli.do during DDD Brisbane 2022, I wasn't able to answer them all, so I've attempted to do that here:
How do you encourage developers to document their code inline? So that code doco can be rendered in the build pipeline.
It’s not something I actively encourage, but it depends on the type of software you’re writing. As with most of the stuff I’ve presented here, be pragmatic.
Through the pull request process is a good way to ensure that code is documented, if required. I would suggest documenting code inline if the intent of the code can’t be clearly understood by a mid-level developer.
However, if you’re creating a library or API that is to be consumed by 3rd parties, then inline documentation might be more useful. In this case I’d look at using convention tests or some other process in your CI build to break the build if a developer adds new code without the expected documentation.
Can you recommend a good starting template for an Architectural Guidance doc?
Software Architecture for Developers – Simon Brown
Creating Software with Modern Diagramming – Ashley Peacock
As much as I would hate to recommend TOGAF...
Any alternatives to PlantUML? Have you looked at mermaid?
Yep, I’ve used mermaid. It’s a good option because it seems to be natively supported by more wikis and github etc.
The reason I didn’t talk about mermaid much is because it’s a bit limited in functionality compared to PlantUML. Having said that, if it’s supported by your platforms then mermaid is a good option. It’s also relatively straight forward to move from mermaid to PlantUML later if you need the extended functionality.
From a documentation point of view, a couple of people suggested Asciidoc during the Q&A session. I haven’t looked into this heavily, but I think it’s worth a look as well, especially for creating large-scale user documentation.
Another project I recently came across is kroki.io – it seems to be an amalgamation of a bunch of other text based documentation projects.
After the DDD presentation, Daniel Mackay actually reached out to me about a couple of blog posts he's recently done on this topic that are worth a read:
- https://www.dandoescode.com/blog/plantuml-vs-mermaid/
- https://www.dandoescode.com/blog/c4-models-with-structurizr/
Any tools for exporting tables from Excel to markdown?
There’s actually a Visual Studio Code extension for that. If you just want to copy/paste tables this is a good option:
https://marketplace.visualstudio.com/items?itemName=csholmq.excel-to-markdown-table
I’m not sure about what you’d do if you wanted to extract a table as part of a CI process though.
What would you recommend for BPMN?
Good question. I haven’t done a lot with BPMN.
When I did have to view some BPMN documents recently I used Visual Studio Code plugin to visualise the diagrams, but that’s about the extent of my experience unfortunately.
I know PlantUML doesn’t currently support it because there’s an open issue discussing this.
Can you do cloud infrastructure diagram? Also, can you add images (logos)?
Absolutely. There are a ton of PlantUML libraries for this: