Devoxx United Kingdom 2019 hosted a documentation birds-of-a-feather (BOF) session: Dan Allen lead this session called “Writers Write!”, with Ixchel Riuz and Alexander Schwartz (me) being co-leads.
For all participants Dan had four questions that lead us through this session:
- What tools do you use?
- What challenges does your organisation struggle with?
- What challenges do you have in your personal work?
- What trends do you see?
This document is a write up for those who were unable to attend this session. It contains both a summary of the session from notes I’ve taken and some of my personal reflections, therefore it’s not a perfect transcript. Full disclosure: At work I use Asciidoctor for documentation a lot, and in my spare time I work on the IntelliJ Plugin for AsciiDoc.
I hope you’ll find it useful and it encourages you to join a documentation BOF session in the future, or even organise one yourself at a local IT community meeting or at a conference.
Please get into contact with any of us if you have questions or if you want to discuss a topic in detail.
Participants
The participants where from diverse backgrounds. While most had a developer background, we also had people specialized to work as technical writers. One person worked on a writer’s team, but she shared that dedicated writer’s teams were in a decline within her organisation.
We all agreed that writing takes skills, and a project benefits from a professional technical writer. The writer structures and organises documentation and ensures that we document the right things for the correct audience. It is similar to business analysts structuring requirements, processes and use cases, or IT architect structuring code, components and systems, or testers structuring tests and test strategies.
Participants mentioned examples of how documentation helped them to get their jobs done, for example documentation for interfaces to integrate with neighbouring systems and using new libraries and frameworks.
Tools used
The set of tools was diverse: starting from coder’s tools like Git and Atom to JavaDoc, Gliffy, Swagger, Asciidoctor and Antora. The relation to Confluence seemed to be a love-hate-relationship, but in some organisations everybody uses it, despite the problems to link its content to releases and other quirks.
While older versions of Confluence feature a markup language, the new WYSIWYG mode sometime gives me troubles when someone else is editing the page at the same time (co-editing). I found myself in situations more than once where I couldn’t undo a change because it was auto-saved.
Yet Confluence solves — in its own way — the problems of distributing information, commenting on existing documentation and being notified of changes. It also manages access to information that must not be publicly accessible. The search mechanism is a matter of last resort to find a piece of information. As it will retrieve only documents for a keyword typed into the search bar, I find only documents I’ve written myself, or have read before. Related documents remain undiscovered.
Only structuring information can help to find your way around. But far too often I found myself stuck with a navigation that was incomplete or incomprehensible for me.
Challenges of the organisation
A common challenge was outdated or incomplete documentation when development had stopped. Sometimes teams were left with documentation they didn’t understand, with problems of shared content, versioning, ownership, missing details, different nationalities and reception. Readers were looking for documentation covering domain models, use cases, test cases and patterns.
Writing documentation as code becomes a problem when it is trapped in a process designed for code changes. This might lead to dead ends where the documentation can’t be changed once the software is released or an extensive review process for every change. Dan shared examples where the process for documentation matched the documentation’s needs. It can for example live in the same Git repository but in an independent branch where it has its own code review guidelines and an independent release procedure. Yet all code will be in a single repository and can be reviewed seamlessly.
Ixchel mentioned that a lot boils down to realizing that Git is handing around patches to a file. Once non-developers understand that Git is about moving around patches, they will run away from the pain of Microsoft Word and Excel and it is a done deal. After a training, some writers made even more efficient usage of Git than developers who picked it up “on the go” in their projects.
Still the coding tools based on Git miss the collaborative editing we have with Google docs or Sharepoint. Visual Studio Code has some collaborative editing; maybe we’ll see a centralized session on GitHub soon that allows collaborative editing.
Dan shared his experience that an information architect enables teams for effective documentation by creating a navigation structure, an outline and sorting out bad content. This can have a lasting positive effect on your project. Once the structure and templates are there, people can continue to fill the structure with content. You can use template pages (be it in confluence or for a code based solution like Asciidoctor). Sometimes you need to restructure templates and existing content. With code based solutions you can refactor your documentation across sections and documents.
If you don’t have access to an information architect, re-using existing structures for documentation can help you as seeds for your documentation: Again, writers can fill this structure with content as the project evolves. One of those templates is arc42 that comes ready-to-go for Asciidoctor, but also other formats.
Once documentation exists, how do we keep it in shape? Tools like Acrolinx (a commercial enterprise content management system) can validate documentation. Simple linter tools like eslint can ensure structure and consistency of documentation. They will nag you when you use words you shouldn’t, and treads on your toes when your sentences get too long.
Not writing documentation bites you the same way you get bitten by not writing tests. A standardized and automated “publishing stack” might pave the road to more (and better) documentation. Tools like Terraform can set up everything needed for documentation starting with the repository, permissions, publishing process, and finishing with a continuous integration job.
Challenges in personal work
Some questions reoccurred that we had on the tools- and team level: Searching in one or multiple projects, how to start with a blank page and structuring ideas and content.
When do you forget content? Ixchel shared an experience from a documentation migration project: You can start with the most important content. And leave all other content on hold in an archive just in case someone needs it. Once it is needed, pull it from the archive and convert it on-demand.
In his most recent projects Dan added Algolia as a search engine for docs. It is an online service and they provide free and paid plans for different needs. Dan experienced that you don’t need Google’s capabilities to search documentation: As the corpus (number of documents) is small, the results are still good. Once you’ve set it up, you can analyze the search queries to improve the documentation both in terms of structure and missing content. I am concerned with GDPR and some of my clients don’t want to use cloud services, so I want to try out a self-hosted solution like Lunrjs soon.
Another challenge was “paged media”, usually known as PDF. Creating a PDF from Confluence is usually problematic as it lacks a proper header, layout and versioning information. Some participants used Asciidoctor to create a PDF: Although some styling is possible, it is limited in its capabilities. If the receiver requires a highly styled document, Asciidoctor PDF will not deliver the PDF you need. The future path of Asciidoctor is probably styling HTML using CSS and creating a PDF from the HTML pages. Media queries create different output formats. A glimpse of this future is available with asciidoctor-pdf-js that uses Puppeteer, a headless Chrome browser to convert Asciidoctor via HTML to PDF.
Trends — How is the present changing?
Microservices are a trend. They lead to smaller deployable units, more frequent releases and higher automation. Documentation needs to keep pace, both in the number of releases and automation. The more microservices you have, the more interfaces you’ll have. To document these there are multiple options: Open API (formerly known as Swagger) vs. Spring Rest Docs vs. Consumer driven Contracts. In a Microservice world documentation is part of the software build and continuous integration cycle.
In such an environment, how would an integrated development (or writing) environment look like? The fastest feedback provides an editor with a local preview (like for example Atom or IntelliJ). The future might bring a full implementation of the Language Server Protocol that allows Asciidoctor to provide editing support independently of the editor, although it is primarily focused on Visual Studio Code.
A staging environment provides the final layout for review when running a full documentation build is too slow or too complicated to set up locally (even in the world of docker). With the advent of Antora creating a preview of a full documentation site locally has finally arrived: It is blazing fast and requires Node (no Docker involved here). Dan presented Antora in a live demo the next day and a recording is available on YouTube.
On the other side fewer emails are being written with instant communication channels like Slack becoming more relevant. While online meetings like Zoom provide the possibility to share a screen, real co-editing in the same IDE with two cursors remains a fragmented market. An IDE like Visual Studio Code has it integrated, while other services like Floobits or Teamhub offer a multi-IDE approach. Newer web-based IDEs might have it included, but web-based IDEs are not for everyone.
Final notes
As we were discussing future trends, one of the technical writers reminded us that developers can be quite tool focused. She pointed out that writing is to provide relevant content in an accessible format to those who use it.
Considering this advice, structure and presentation are more important than the tools. When you visit documentation sites like Asciidoctor or Antora, they still focus on the tool and how to make automation work in a continuous delivery environment. At the moment they don’t link to templates and guides to help you to structure and write relevant content. Sites like the Documentation Guide at Write The Docs cover a lot of the “meta” elements of documentation and also technologies, but don’t provide comprehensive templates.
Templates I’ve used in the past to structure IT architecture documentation are arc42 and ADR. Especially the arc42 template provides structure, advice on each section what to write, plus an example where all sections are filled with content of a demo project.
I hope to see more templates like arc42 covering different topics as it has been of great value to me.
Thank you to Ralf D. Müller for reviewing an early version of this article!