It’s rare that you ever write documentation right the first time.
Instead, what happens is this:
- You write a guide explaining how to do something.
- Later, you realise it could be better. Or maybe the user interface changes and you have to update the screenshots.
- You go back to the guide and improve it.
- Time passes, and then Step 2 happens again, ad infinitum.
As you iterate like this, the documentation gradually gets better and everyone wins. Fewer support calls and more self-supporting users.
But sometimes the digital media used to create the documentation is hard to edit, and this makes iterating a pain.
Here are three types of web-based digital media that people use to write documentation:
- PDFs
- Videos
- HTML webpages
PDFs
Iterating on PDF documentation isn’t much fun because PDFs are typically hard to edit. Say your PDFs are Word docs that you publish as PDFs. To edit a PDF, you need to track down the original Word doc that was used to generate the PDF. Then you need to edit it, export it as a PDF and reupload the new PDF to the web. Sometimes you need to delete the old PDF from the web too. You’ll want local copies of the web-based files, and everything needs organising, versioning; maybe you’ll need to manually append numbers to the filenames so they’re called instructions_V02.3.pdf; maybe you’ll need to archive the now out of date instructions_V02.2.pdf.
See more here:
Why GOV.UK content should be published in HTML and not PDF
Videos
There are some good things about video documentation. Screen recordings capture the animated features of an interface: the buttons and menus that appear when you hover you cursor over the right place. Zooming in and out on the UI is a neat way to show where it is on your screen that you’ll find the small button you need to click.
But screen recording videos are a nightmare to edit. If I want to tweak a video, I need to find the original Camtasia project. Then I need to re-record the part of the screen recording that needs fixing, or more likely make a brand new one from scratch. Fixing the narration and subtitles involves re-writing and re-recording. The video needs to be exported out of Camtasia, then uploaded to a video hosting service in place of the old one, and then that video will probably need to be embedded on a website somewhere.
Consequences of PDF and video documentation
The main consequence of PDF and video documentation being hard to edit is that you start to ignore the feedback you’re getting at Step 2.
Worse case scenario, you start to convince yourself that you got things perfectly right the first time and that it’s not your documentation, it’s the feedback that’s wrong.
But more likely, you’ll listen to the feedback but won’t want to act on it. It’ll hang around in the swampy lagoons at the bottom of your to-do list.
HTML webpages
Fortunately, there’s a promised land: writing documentation as HTML webpages. They’re easy to edit, which means it isn’t a pain when you realise they need to be improved or brought up to date.
