Necessary but Forsaken

• Tue, Jun 13, 2023
• 2-minute read

Most people, if not everyone involved in a software development project, would agree that documentation is an essential part of the process. It’s a fact that developers consider documentation to be an essential tool to understand and get started using a software product.

Technical documentation remains a top online resource for developers learning to code, according to the latest Stack Overflow Developer Survey.

However, it is also one of the most overlooked aspects of the software development life cycle. Why? There are a few reasons:

• Time constraints: time-to-market must be fast, so teams need to prioritize tasks to meet tight deadlines. When focusing on shipping the product as fast as possible, most efforts are spent on code and feature completion.
• Lack of resources: everyone agrees it would be nice to have good-looking, useful documentation in place, but no one has time to do it: developers are busy writing code, and the rest of the team is also busy with their own tasks.
• False solutions: When dealing with tight deadlines, documentation can be seen as a low-priority aspect of the product, so teams recur to false solutions, such as:
  • Generating automated documentation.
  • Writing “self-explanatory code.”
  • Writing the documentation as an ’extra’ task for developers.

With exceptions, these are false solutions because well-written documentation goes beyond using automated tools from –often– not-so-well-commented and not-so-self-explanatory code.

Additionally, while many developers can write great documentation, that’s not always the case; not all developers possess the writing or information development skills to create cohesive and complete documentation; besides, as mentioned before, they have to focus on their actual development tasks.

What to do?

The reality is that, more often than not, documentation will remain an afterthought for many people, especially those focused on product delivery. Technical writers must follow a strategic approach to succeed in these scenarios.

The most important aspect of the strategy should focus on prioritization and follow an incremental approach: Identify the most critical documentation tasks.

• Focus on the documentation needs that will have the most impact and build upon them.
• Collaborate with developers and other team members. The more people care about documentation, the better.
• Use existing resources. Sometimes there’s already information on Confluence pages, README files, or other places. Explore the available resources and ask questions.
• Deliver and assess: as you start delivering documentation, evaluate the next steps and re-prioritize if necessary. Remember to constantly communicate with stakeholders to ensure that the deliveries meet expectations.