Docs as code doesn’t have to mean Markdown and Git
Published on 19 October 2023 by Andrew Owen (7 minutes)
After almost 15 years as a technical writer for software companies, I’m a convert to the docs as code philosophy. But while I like Markdown and Git (I use them for this website), I wouldn’t use them to document enterprise software. I’d miss the benefits of dedicated documentation tools like structured authoring, single sourcing and high quality PDFs to name a few. You may have been told that you have to give up your tools and become more like a developer to do docs-as-code, but I don’t think that’s true.
Write the Docs has this to say:
Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code:
• Issue Trackers
• Version Control (Git)
• Plain Text Markup (Markdown, reStructuredText, Asciidoc)
• Code Reviews
• Automated Tests
This means following the same workflows as development teams, and being integrated in the product team. It enables a culture where writers and developers both feel ownership of documentation, and work together to make it as good as possible.
It lists the benefits as:
I fundamentally disagree with this interpretation. What’s next, illustrations as code? Instead of using dedicated tools, should we have all the illustrators write SVGs in VScode? Of course not. I think the problem here is the mistaken idea that because docs are text and code is text, that they are the same thing. Docs are not code. But they are a deliverable, and as such there is value in aligning the documentation process to the development process.
First, you need to know what software development lifecycle (SDLC) the developers are using. If they’re still doing waterfall, it’s unlikely that you’ll be called upon to do docs as code. But if they’re doing continuous integration and deployment (CI/CD), agile or DevOps then expect to have a discussion about it sooner or later.
This is one area where I’m completely onboard with the orthodoxy. If developers are tracking issues in Jira, technical communications should also be tracking issues in Jira. Minimal docs should be part of the “definition of done” whenever there is a change in software behavior that affects a user. Developers should write public facing descriptions of changes that can be automatically pulled directly into release notes.
Documentation should be under version control. However, the needs of documentation and code are different. Historically, one of the most widely used versioning system was the Concurrent Versions System (CVS). But due to its limitations, it was eventually replaced with Subversion (SVN). But then Subversion fell out of favor and was replaced with Git. However, the software development process and the writing process are different and unless you have a component content management system (CCMS) with built-in versioning, Subversion is a better choice.
In software development, developers create feature branches and work on content, submitting a pull request (PR) when they are done. The code is reviewed and if the pull request is approved, the code is merged into the main branch.
Documentation is messier. Writers create or update content and then send it for review. But there tends to be much more back and forth at this stage. After review, the content may need to be translated. Translations must be reviewed. When the translation is complete, you don’t want the source to change. For this you need locks, which are a feature of Subversion but absent from Git.
Plain text (Markdown, reStructuredText, and to a lesser extent Asciidoc) throws away the key developments in tech writing since SGML was standardized in 1986:
If you are given no choice other than to work directly in a repository then I strongly advise you to install TinaCMS locally. You can use .gitignore to exclude its files from being checked into the repository you are working on. It will give you the benefit of a more writer-focused editor and the ability to use browser-based writing assistants like LanguageTool (links for both tools are at the bottom of the page).
But if you are doing enterprise software documentation, then you should demand an XML-based solution. I prefer DocBook, but as much as I dislike DITA I would rather use it than Markdown for this purpose. Most software integrated development environments (IDEs) don’t even have a default spellchecker.
The assumption is that reviews should be done using the PR system in Git. However, there’s no reason the review stage can’t be built into the workflow in the issue tracker instead. QA doesn’t review the source code, it reviews the software. And the same should be true for documentation review. You want developers looking at the published documentation, not the source. This simply means that you need to create a staging site for your documentation that’s only available internally.
There is no automated way to test if documentation is any good. The most a test is going to tell you is if documentation exists or not. But automation is good. Even if you’re not doing CI/CD, deploying the documentation to staging should be part of the software build process. If you’re using tools on your own servers, this can be scripted. If you’re using a CCMS for documentation, this can typically be done through API calls.
One area where automated tests can be useful is in validating context-sensitive help (CSH) links. However, first you have to persuade product that every feature should have its own CSH link.
If you want to integrate writers with developers, and you should want that, then the best way to do that is to co-locate them. If everyone is working remotely, then they should be in a time zone with a reasonable amount of overlap. If you have hybrid or full office working, then the writers should have desks in the same area as the developers. Writers should attend developer meetings such as stand-ups and retrospectives. And crucially, writers budgets should be owned by product.
It’s a nice idea that writers would be able to block a feature from being merged if it doesn’t have accompanying docs, but I’m doubtful that there are any real world examples where this happens. Developers are very protective of their code, and even getting writers read-only access to a repository can be a challenge in many organizations.
But the most important thing is that writers are working at the same cadence as developers. If you can ship software at any time, you need to have a defined time to the availability of docs. This needs planning, but it’s much better to do that in an issue tracker than a source repository.
If you can get your developers to do a first draft of documentation, that’s great. But I suspect one of the reasons for pushing writers into using developer tools is that it’s a path of less resistance than trying to get developers to use writer tools. So if developers don’t want to learn new tools, have them do the documentation in the issue tracker. Then use automation to export the content and generate docs based on it. Again, if you’re using tools on your own servers this can be scripted or if you’re using a CCMS it can typically be done through the API.
Back when I started teaching myself assembly language, I did what everyone else was doing at the time. The code was in one monolithic text file, and I used to use file copies for backup. This was a terrible system. What should be surprising, but probably isn’t, is that where documentation is concerned, even enterprise software companies are often still using a similar approach. Monolithic Word docs with backups stored in folders on networked drives. Pretty much any alternative is likely to be an improvement. At the start of my career as a technical writer, companies were only just starting to see the value of using code repositories to manage documents. But we’ve come too far in technical writing to throw away advanced solutions that provide great user experiences in favor of a simplistic approached to aligned work practices. The root idea of docs as code is a good one, but a less dogmatic approach is required. How’s that for a hot take?