Common Mistakes in Engineer-Authored Docs and How to Fix Them

Over the last six months, our development team has embraced the "docs-as-code" approach (you can learn more about our journey in this article). Regularly reviewing the documentation created by my colleagues from the Tech Division, I compiled a list of the most common issues found in writing technical documentation.

In the article, I will show you how to fix these issues using the tools of the “docs-as-code” approach.

Issue 1. “Docs writing is not under our responsibility”

Dealing with documentation on an ad-hoc basis is like shooting yourself in the foot for the entire development team. If the team lacks the capacity, it's a compelling reason to make documentation maintenance more technology-driven and predictable.

Fix:

• Integrate the “docs-as-code” approach to the development of the documentation. This way, you can update the documentation iteratively, alongside the codebase, without the risk of accumulating technical debt.
• Develop or integrate a space or a platform that can render tech docs and serve as a single source of information.
• Utilize an integrated development environment (IDE). An IDE enables you to incorporate plugins and create custom scripts for documentation development. IDEA is an excellent tool for docs writing, but you may have your favorites among applications.
• Install a spell-check plugin to safeguard against typos. Adding the plugin to your IDE is a quick and easy process.
• Adopt the internal guidelines specially crafted by your company, taking into account insights from the technical writing community (if you have any), to establish a standardized approach for developing documentation within the company. Following these guidelines will streamline the documentation process, saving time in contemplating what and how to write accurately.
• Automate checks based on the guidelines to significantly reduce or eliminate time for docs review.
• Template everything possible and agree with the team on standardizing documentation components.

I will offer valuable resources that will boost your confidence while working with technical documentation. I believe that these resources are comprehensive enough to equip you for handling tech docs effectively:

• The "Google Developer Documentation Style Guide" serves as a comprehensive handbook for developer documentation. It covers everything you need to know about formatting, punctuation, listing, and adding code blocks. This guide is sufficient and has been a valuable reference for developing our internal guidelines, from which we borrowed some best practices.
• “Docs for Developers" is a must-read book for anyone involved in working with developer documentation, whether they are developing, writing, or maintaining it. The book features several renowned and esteemed authors in the field of technical writing.

• "Docs Like Code" by Anne Gentle, a technical writer, is a practical guide that showcases the documentation culture in OpenStack. Through practical examples, the author explains why documentation should be managed in GitHub and how to implement technological processes for effective documentation. The book also offers valuable insights on writing professional documentation, regardless of whether you are a developer or a technical writer.

• I will also mention internal guidelines for writing technical documentation, which should include templates and formatting rules. Such guidelines exist in every company. Typically, they are developed collaboratively with a technical writer-pioneer and dev docs champions and evolve as the documentation culture within the team grows.

Issue 2. Writing documentation solo

Developing the entire documentation alone and then submitting it for review carries the risk of creating redundant or irrelevant documentation that may not align with the intended purpose.

Fix:

• Always start with an outline and share it with your team lead, product owner, technical writer, or any colleague willing to provide their expert opinion.
• Write step by step and assign pull requests for review on the same above mentioned colleagues.
• Collect and work on feedback.
• Consider the comments. And take it easy on the review tone of voice, sometimes it could be harsh, but it is merely a peculiarity of the review process.
• Don’t overlook the documentation flow. Below is the general flow adopted in our company, but the features of this flow could depend on a development team as well as the company:

Issue 3. “Those who need to understand will understand”

From time to time I hear from teams: “I am writing for the development team," "those who need to will understand," "this is how it historically evolved within our team”.

But professional jargon and anglicisms require appropriateness and consistency. Excessive use of them may lead to documentation resembling the notes of a mad engineer.

For documentation, use the simplest words and structures possible. One of the main principles is writing for scrolling. Documentation can be challenging to write since it is often extensive, but readers rarely go through it from cover to cover. Instead, they tend to scroll or use keyword search. Therefore, the text should be easily understandable when opened from any part.

Fix:

• Check English terms and professional jargon using dictionaries and current norms (or simply Google them). If a word exists in the dictionary, write according to the rules of your language orthography.
• If the word is not present in the language, write it in the original language, and provide a translation to your language in parentheses.
• Add the word to the glossary section, and abbreviations to the list of abbreviations and acronyms. This is especially important for "proprietary" abbreviations (no matter how much is mentioned or written about PO, its meaning is still one of the common questions when reading the documentation).
• Consistency – stick to the chosen writing style and abbreviations throughout the documentation (better for all available documentation in your company).
• Plan the document navigation carefully. There should be a quick way to find the relevant section without having to read the entire document. Therefore, it is essential to thoughtfully structure the content with clear and concise headings. Internal documentation templates should be developed for simplicity and convenience.

Issue 4. Writing documentation simultaneously in multiple places

For documentation, having a single source of truth – one space where you can find the necessary information without worrying about its accuracy is crucial. For our technical documentation, an in-house developed platform serves as such a space. Avoiding fragmentation of documentation in different spaces is essential to prevent misleading anyone with outdated information.

Fix:

• Before publishing tech documentation anywhere, ensure that it doesn’t exist somewhere else, if it came up that the company uses several spaces for knowledge sharing.
• Archive or delete (if you have ownership) outdated technical documentation. If you are concerned about premature deletion (for instance, due to external links to the page), add a callout stating that the page is outdated, and the current documentation location of valid docs, where further updates should be made.
• If you come across valuable information or insights, add them to the documentation. Do not leave it in Slack or anywhere else, especially in private chats. Knowledge worth sharing!

Posted by Anna Goncharova