The Easiest Way to Keep Product Documentation Up to Date

Documentation.

The backbone of successful and beloved products, but difficult to keep up to date given how quickly products evolve. Not to mention dreaded by software developers, who would instead write code.

Given these challenges, I’ve found that the easiest way to keep product documentation up to date is:

While working on a product, update its documentation simultaneously.

At face value, this appears simple enough, but often isn't.

Why This Approach?

When building your product or creating a demo, chances are you’re focused on a specific area or “theme.” This includes installation/setup, hosting, interacting with the CLI, debugging, UI theming, backend API integration, etc. Updating documentation simultaneously is much faster when the related product concepts are fresh in your mind. This is often the reason why developers shy away from documentation updates - it’s left to the end of the current task or sprint, making it easy to fall to the wayside. Or worse: “when we get to it” which, spoiler alert, is often never.

Over time, a mountain of product changes piles up, making the situation feel unmanageable. Therefore, the trick to get your team to update documentation as part of their regular workflow is to reduce the friction involved.

How?

When you sit down to begin a new task, take a few seconds to pull up the docs that are related to that area of work. Skim through it, putting yourself into a documentation mindset. You’ll start to notice details that are out of date or outright incorrect.

Next, begin the product work. Pause occasionally on each major step to compare the existing documentation to the actual work you’re performing. Things to look out for include:

• Is the page still factually correct?
• Are there additional details to add? Perhaps a 3rd party tool’s workflow has changed, or a new step was added recently.
• Could further clarification help? For example, the docs are technically correct, but from experience, you’ve learned that users should watch out for problem X and Y.

Make updates to the page. Once the product or demo task is complete, submit the documentation changes.

In my experience, this approach works best when creating product demos/tutorials and the documentation for the area/topic already exists in some form. This way, you avoid admin-related work (aka yak shaving) that distracts from the original goal of updating the content, such as creating new pages, adding new links to the table of contents, fiddling with styling/design concerns, and so forth.

A Concrete Example

I was in the middle of building a Capacitor demo app that showed off all of its plugin features. I decided to host it as a web app on Firebase, giving my coworkers a chance to provide feedback after testing it on their mobile devices. While working on the demo app, I opened the Ionic docs page on Progressive Web App hosting and compared those instructions to the actual steps I needed to take. After the app finished deploying, I submitted the following changes:

• Adding a link to the Firebase web console. Ionic users need to create a new Firebase project before completing the other hosting steps.
• Updating the firebase init command’s user prompts. An important one was missing regarding the public directory containing the compiled web app. For Ionic apps, the standard build output directory is www (not public as Firebase suggests).
• Providing a complete firebase.json configuration file that users can compare.

Result

Updating the Firebase hosting page added a mere 30 minutes to my demo app hosting task. I clarified and expanded some of the trickier aspects of deployment, which will now be evergreen for quite some time.

Following this approach, your documentation stays up to date, and improvements can continue at a sustainable pace, all while removing the burden on the development team.

Comments

[Dave Horan]

Hey Matt,
This looks like a good approach, and one I've taken several times when working in an existing project. One pitfall I fell into was correcting/fixing bad docs I came across while adding changes to the parts I was updating.

What about documentation generators like Sphinx? I've had some success in getting these in place, and convincing the team devs to simply update their inline comments (Python) so the generator will pick things up.

[Matt Netkow]

Thanks Dave! Haven't heard of Sphinx, but yes that's a great approach. I wrote this from the standpoint of long-form guides, but anything that automates/generates docs for you is definitely a big win. I believe our team does something similar with the UI Component pages of the Ionic docs.