HTML works well for documentation because it’s easy to edit, and this means you’re more likely to improve it in response to feedback.
The kind of documentation I’m talking about
When I say documentation, I’m talking about guides on how to use a piece of digital technology.
Things like:
- How to upload a file to a virtual learning environment
- How to add an image to a WordPress blog post
Your documentation won’t be right the first time
Here’s what happens in my experience:
- 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.
By iterating 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 are hard to edit
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
- edit it
- export it as a PDF
- 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
.
The folks at GOV.UK wrote a good blog post about why HTML is often better than PDF:
Why GOV.UK content should be published in HTML and not PDF
Videos are even harder to edit
Video is another format that people use for documentation.
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. Say I created the original video using Camtasia (software for making and editing screen recordings). If I want to tweak the 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.
If documentation is hard to edit, you don’t improve it in response to feedback
The main consequence of PDF and video documentation being hard to edit is that you ignore the feedback you’re getting at Step 2.
You’ll realise your documentation could be better, and you’ll notice that your screenshots of the interface have gone out of date. You’ll know things need to change but you won’t have time to make the updates. The unwanted task of fixing things will hang around in the swampy lagoons at the bottom of your to-do list.
HTML is easy to edit
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.
That’s why most documentation should be in HTML format.