Solutions to manually maintained lists

Do you find yourself manually maintaining long pieces of documentation that quickly becomes out of date? The aim of this article is to address and suggestion a solution to this common technical writing pitfall.

If you receive customer feedback for any amount of time, you may start to notice trends or common issues customers find with your documentation. One issue your customers may find is with manually maintained lists. Customers let you know that the list is out of date, versions are no longer supported, or new versions exist but aren’t listed.

For example, imagine you have a table of supported versions for your software product. This table has many columns and rows that list supported versions, dates, and exceptions. Manually maintaining this table becomes a pain as it updated infrequently and without communication from your team who is in charge of making updates.

You can update this list manually based off your customer’s feedback. Problem solved, right?

The list maybe accurate now, but in a few months the list will quickly become out of date, and you’ll be receiving the same customer complaints. In a perfect world, the developers who are making updates will communicate any change that will affect documentation; however, in my experience, this is the exception to the rule.

To address the systematic issue, you can meet with a subject-matter expert (SME) and talk about the pain points to manually maintain this list and come up with a way of removing the friction. Some solutions may include:

• Automating updates to the list.
• Giving your SME write permission to the list to streamline updates.
• Create an open-source repository and allow your customers to create pull requests.

Each solution has some upside and downside, but the important part is finding what works best for you and your customers.

Automating updates to the list

You might be able to automate the list if your organization contains an API that will list the versions. Calling the API and saving the outputted results in a text file is one example. You can take it a step further and create a cron job scheduler that will periodically update the table for you.

I’ve included a small Python tutorial on how you can automate the “last modified” date in your documentation here.

SME write permissions

Talking with a product manager and making it a requirement to update your table will ensure the table contains the most recent information. Work with the product manager to ensure developers have the correct write permissions to your files, and document the internal workflow for the developers who will write to your file.

Open-source repository

If your customers are taking the time to submit feedback, they’d likely rather take the same time and energy to submit the documentation update themselves. Using GitHub or GitLab and hosting your documentation there will allow further updates to happen too. Ensure you have quality control and reviews in place before accepting a pull request.

These are just a few ways you can streamline updating tedious lists in your documentation and free up your time to focus on more complex issues while keeping your customers in mind.

Have you found a solution to the problem described above that works well for you and your customers? Let me know of any additional ideas in the comments below.