How Not to Publish Documentation

Good documentation is critical to the success of any product. Write clear deployment & configuration information, and you’ll have a higher project success rate. Detailed command references and troubleshooting information shorten the time it takes to resolve issues, and reduces support calls. But writing high-quality content is only one part of it. You have to make sure that the documentation is easy to find, and easy to access.

Recently I’ve been reading some HP Networking documentation, and it’s been a study in how NOT to publish docs. Let’s take an example - I want to see the Release Notes for the latest firmware for the 12504 switch. Here’s the workflow:

First go to HP.com. There’s a drop-down “Support” - that looks likely. Click on that, then “Support & troubleshooting”:

support_page

Enter “12504” in the Product name/number box, and hit search. We get 3 results:

3 matches

Looks good. Let’s click on “HP 12504 AC Switch Chassis”. Hmmm. A very jarring change of layout, but it looks like we’re getting closer:

hp 12504 Support Page

Let’s follow the link for “Manuals”:

12504 Manuals

Software Reference sounds likely, let’s take a look at that:

software reference

The version information seems to be mixed in with the Title there, but it looks like the most recent file should be the one. Except..it says it’s a PDF. Why not an option to view in HTML or PDF? HTML is much better suited to online reading, but I can understand that some people prefer a PDF for offline viewing. Note the URL: http://h20565.www2.hp.com/portal/site/hpsc/template.BINARYPORTLET/public/kb/docDisplay/resource.process/?spf_p.tpst=kbDocDisplay_ws_BI&spf_p.rid_kbDocDisplay=docDisplayResURL&javax.portlet.begCacheTok=com.vignette.cachetoken&spf_p.rst_kbDocDisplay=wsrp-resourceState%3DdocId%253Demr_na-c04220329-1%257CdocLocale%253Den_US&javax.portlet.endCacheTok=com.vignette.cachetoken

Yes, seriously, that’s the URL. Let’s see what happens when we try to load it:

adobe error

Really? REALLY??? OK, so maybe it’s something to do with the PDF rendering in my browser (Chrome in this case, but Safari/Preview sees the same thing). Let’s try doing a right-click, Save Link As on that URL:

Download Title

I kid you not. Every. Single. Document. that you want to download from HP Networking wants to save as “Download.pdf.” Unless maybe it’s a zip file…and then it’s “Download.zip.” So now I need to manually re-name everything, and of course I can’t just do a rapid right-click, download on a whole lot of links. Instead I need to pay attention, manually re-name, and then I end up with a heap of inconsistently named files.

Does anyone think about how real engineers are supposed to use this stuff? It really doesn’t need to be this hard. It is 2014. There is no excuse for making documentation difficult to use. HP Networking should be embarrassed by this.

[UPDATE 15/7/14] HP now has a KB article on “Resolving PDF Portfolio Viewing Issues.’ Among the other notes, it says that Portfolios may not open because Adobe Reader no longer installs Flash by default. If a PDF viewer requires Flash, that should be a big red flag telling you to run away now. Maybe they’ll move to a version that also requires Java?