In this Write-the-Docs London talk on 2 May 2024, speakers shared their experiences with using software tools to automate the publication of their companies’ documentation.
Because these software tools are also used by programmers for computer code, this approach is also known as “Doc-as-Code”.
Vladimir Izmalkov gave the first presentation. He gave a broad overview of common software tools for Doc-as-Code, including (amongst others):-
Vladimir then shared VK Private Cloud’s experience with migrating documentation from Confluence to Git in a short time frame, and in the process changing the underlying document format from Microsoft Word to AsciiDoc.
Highlights include finding and mastering a free open-source tool called Pandoc, where users has fine-grain control over many aspects of document-format conversion; and the huge difference in workflow once it became possible to use git branches and merging to manage different versions of the documentation.
Ian Selwyn-Smith gave the second presentation. He explained Caplin Systems’ experience with migrating and publishing documentation in web format. Highlights include weighing pros and cons in choosing the relevant technology stacks, bringing the management and the developers on board with these choices, and liaising with the design team to make sure the new website has the right look and feel.
Finally, Polina Zaichkina shared Codat’s experience with migrating into Doc-as-Code. Highlights include liaising with developers for input and technical help; the decision to make the entire documentation open source; the processes that needed to be set up to handle pull requests (i.e. suggested edits) by the public; and how some clients cited the superior documentation as a factor that makes Codat’s products stand out from its competitors.
The evening concluded after a brief Q&A with audience going deeper into the topics covered by the speakers.