.png){kind=small}
.png){kind=small}
The proliferation of agile methodologies has transformed the world of software development in many ways, and documentation is not an exception. The Manifesto for Agile Software Development mentions the issue from the get-go, and not in a very complimentary way, declaring the valorization of "working software over comprehensive documentation". This excerpt has been a pretext for leaving documentation aside, helping to claim that it is a waste of resources rather than an asset that adds value to a product.
However, this view is flawed and it’s even disallowed by the Manifesto itself, which states that "while there is value in the items on the right, we value the items on the left more”. That is, documentation does have value - even when we speak of agile methodologies - although it is important not to place it on higher ground in relation to working products.
Yes, documentation takes up resources, as any corporate activity does. That is why over documenting is an unnecessary expense indeed, both in terms of time and personal effort and in terms of storage space. But documenting too little, or documenting poorly, is also a waste of resources. And it that can be reflected, for example, in unnecessary support tickets due to the lack of material assisting customers or in more time and effort spent on developer onboarding.
That is why the decision of what, how much and how to document must always take into account the risks and costs of documenting more or less than what is enough. The main question, then, is not whether we should document (we should!), but how we can find the right measure of documentation that is, like the product development process, agile.
I hold that the first fundamental requirement to find this measure is not to set documentation and coding completely apart. And that goes also for end-user documents, such as guides and tutorials, which are the focus of what I call technical documentation in this text. In fact, there is an increasingly widespread concept about this, doc as code, which urges us to see and treat documentation as a piece of code.
The fundamental idea behind this concept is that treating technical texts about products as code - including using the same tools applied to software development - allows us to include documentation as a deliverable, a part of the product as a whole. This reduces inconsistencies between documentation and the working product, makes it easier to keep texts updated and avoids unnecessary rework.
And this change in the way of viewing documentation can have a significant positive impact on the quality of the writing and publication process. This is because coding, revision and versioning tools - as well as project management methodologies - which are widely used in software development can make the process of developing documentation faster, more collaborative and organized.
To be a bit more thorough regarding the inner workings and benefits of documentation as code, let's consider two dimensions of documentation development: writing the texts and the broader process of monitoring the life cycle of each document, which includes the writing, but also the design, reviews, tests, publication, continuous improvement and metrics analysis, the workflow for short.
When you need to write texts that won't have to be updated frequently and must only be converted to PDF once, word processors, like Microsoft Word, are a great option. But software guides and tutorials are, increasingly, living organisms. They must always be revised and improved, usually collaboratively, as products change over time, and they are most frequently published on websites, not (exclusively) shared as PDF files. Binary files, such as .doc, which are heavy, take up a lot of disk space, and require word processors to be written and viewed, are simply not the right choice for the vast majority of technical documents.
Treating documentation as code means, first, that it must exist in the same environment as the code does. Following common practices, this means that it will be maintained in code repositories that support version control (or, more specifically, distributed version control), such as Github and Bitbucket. And the file format must be accepted by the repository service. This takes us to plain text formats, which are lightweight and can be viewed in any text editor.
But that doesn’t mean that we are going to write product documentation as TXT files on Notepad. Regarding the format, there are many plain text languages with format and layout syntax. They are markup languages. Personally, I am an AsciiDoc disciple, but you may prefer Markdown or RestructuredText. As for text editors, there are countless great options. I, for one, use Atom, with lots of packages to facilitate my writing process installed. In addition to AsciiDoc syntax highlighting, I use a tool to check spelling errors and take advantage of the search and replace feature, which is way more advanced than I would get in a word processor. Using regular expressions, I quickly find and replace words or phrases in a file or an entire project. Organizing texts in projects is itself a huge benefit. It’s easier to find the text you need, as you can see all project folders from inside your editor. Also, as each file is lightweight, I can open and work on several files at once, including sharing the same screen space.
There's nothing new here for developers that write technical documentation since they're already used to text editors for coding, even if they are still using word processors to write documentation. Technical writers who are not developers, though, might suffer a bit to leave WYSIWYG (what you see is what you get) tools behind. But getting used to good things is easy, especially when the benefits of doc as code far surpass the shortcomings.
Beyond changes in writing documents per se, what I see as the main strength of documentation treated as code is how easy it integrates into the product development workflow.
Storing texts in code repositories means taking advantage not only of version control tools but also of lifecycle management across different development stages, all reflected in separate branches of one repository. With this, it's easy to insert texts in product planning, including documentation into the project management domain and following the same practices of review and tests before going to production.
As with software, it's possible to solve documentation problems through bugfixes or hotfixes, each with their respective branch, and provision feature versions of the documentation alongside the product. More than that, the text becomes a live entity for real -- with constant updates -- and it's easier to share the work with a team, be it because there's more than one author per text or because there's one author but multiple reviewers in a group of developers.
With the text as part of the delivery, it's also easier to coordinate different roles. Technical writers don't feel so out of place and become a part of the developer team. This incorporation creates double-track collaboration. On the one hand, technical writers feel more at ease to ask developers for input; on the other, they can also pitch in and contribute to the product itself at times. This happens because they must learn every possible detail about how products work and need to test them with the final customer in mind. This can lead to insights and contribute to bug detection. While that’s not the main goal of a technical writer's work, it’s a welcome externality.
This article has attempted to show you some advantages of treating documentation as code. It's worth pointing out, though, that these advantages don't mean that every technical text has to be written this way.
Remember: "agile" is not a specific and well-defined process or methodology. It's rather a set of values, a mode of thinking and organising software development and architecture. Being agile is, more than anything, assessing and implementing the most adequate path to reach a given end while wasting the minimum amount of resources.
Applying this rationale to documentation, the workflow I have just described may not always be the best option. Depending on your audience, the culture of your development team, your specific publication needs, you might reach different conclusions from the ones I've laid out here.
In any case, if writing agile documentation is the focus, it's worth rethinking documentation practices. Am I over documenting? Am I documenting less than I should be? What is the life cycle of the texts I produce? What types of texts do we need to generate and what is the ideal publication method for each of them? Answering these questions is the first step to writing agile documentation. And, after you answer them, the next step is planning your workflows.
