Maintaining Documentation: Make It Easy!




Have you ever had trouble with outdated examples, installation instructions that no longer work, or obsolete references in your documentation? You're not alone. At some point, everyone involved in software engineering has run into problems like these. In fact, a significant portion of documentation issues stems from inadequate maintenance.

There is a wealth of information on how to make reading documentation less painful and more productive, from considerations about information architecture to suggestions for appropriate UI solutions. However, good documentation doesn’t just magically appear — someone must write and maintain it. Therefore, it is important to consider the workflows of documentation maintainers. What issues do we face and what can we do to improve them?

In this talk, we will take a closer look at six blockers commonly encountered when maintaining documentation, such as poor workflow automation, unclear guidelines, and lack of traceability. We will then discuss specific improvements you can implement in your own organization, regardless of the programming language you use or who reads your documentation.

Whether you’re an individual contributor trying to make your job easier, an open source maintainer hoping to get more contributions from your community, or a manager aspiring to remove blockers faced by your team, this talk will outline steps you can take to create an exceptional documentation maintenance experience.

  • Conference: Write the Docs Prague
  • Year: 2022

About the speaker

Emilia Juda-Özbay