ITauthor

For a long time – not without reason – I avoided putting specific version information on the title page of documents. Instead, we put obfuscated details in small print at the bottom of the copyright page that told us (the technical writing team): when the PDF was generated, who created the original draft document, who last updated the published document, and the release number of the relevant software at the time the document was last updated.

One reason for not declaring this information openly on the title page, was an expectation on the part of a few of our customers that each release of a software product should have its own release-specific manual – even if the release was just a bug fix release, where nothing requiring documentation was added or changed. I was determined to resist being forced into producing a new version of a manual where the only change was that “Release 7.5.2” changed to “Release 7.5.3” on the title page.

But the other (real) reason was that there had been times where, I have to admit, new releases of software went out without an updated manual, simply because of a lack of technical writing resource, and my title page coyness was driven by a desire on my part to avoid this being blindingly obvious to the customer. In this situation, you really don’t want to put “Release 9.5.0 – November 2005” on the title page of a manual that may accompany the 9.7.0 release of the software several months later.

But, thankfully, that situation has improved and earlier this year we started putting a simple document version number on the title page of our manuals:

Document version: 1

However, we ran into a problem with this. A simple version number leaves unanswered questions. Does the version number apply to that document, which gets updated throughout the life of a product, through various releases. That is, you wrote version 1 of the User’s Guide for the 1.0.0 release and when release 1.0.1 came around you didn’t write a new manual, you just made a couple of updates – so shouldn’t this be version 2? Or should it be another version 1, because it’s the first version of the manual for that particular release?

By this time we were logging all our new documents and documents updated for a specific release as records in a database. So, continuing the habit of a professional lifetime, I devised an obfuscated code based on database record for the relevant product, plus the record for the document, plus an eternally incrementing version number, to arrive at a unique identifier like:

Document version: 50.8.12

Still no date though. I was still extremely wary of openly declaring the publication date. Old habits die hard.

So, bringing things up to the present – and the reason for this blog post – my new thinking is: less obfuscation, more honesty. Right now the technical writing team is doing really well at keeping the documentation up to date. And my current belief is that if, in future, we start struggling to keep the documentation up to date, then making this obvious to the customer is probably a good thing. If up-to-date documentation is important to the customer, they’ll will raise this with the Support team, the Support team will raise that with me, and I can use that information to back up a request for more resource. If my company wants to keep its customers happy (which it does) then, in this situation, the chances are good that I’m then going to be able to get more resource when I need it.

My new plan for our title pages is to include information like this:

Document ID: 540
Revision number: 1
November 26, 2009

The document ID comes from our document database. Every time we create a brand new document or we update a document for a new release, we create a new document record and the revision number starts back at 1. Updates within a release don’t get a new document record, but the revision number increments.

We no longer need the old obfuscated code that we used to put on the copyright page, with details of who created and updated a document, because that information is captured in our database (and in SVN). The main change is adding the date. Like I said, I resisted doing this for a long time, but I’m now convinced that being open about the publication date is the right thing to do.

Having made this decision I thought it would be interesting to see what other software companies are doing. Here’s what I’ve found this evening after a quick, random and completely unscientific check of some publicly available software manuals. The following shows what document details I found on the title pages of the manuals I looked at, other than the company name, company details, product name, product release number and document title.

Citrix
No other details on title page. Copyright page included:
Document Code: June 3, 2009 (KKW)

Cisco
November 24, 2009
Text Part Number: OL-15574-01

IBM
SC09-4820-01

Oracle
E14481-01
February 2009

Adobe
No other details on title page. Copyright page included:
Part Number: 90081719 (07/07)

Microsoft Press
Traditional book publisher style title page and copyright page. No other details on title page. Copyright page contained lots of info, including ISBN, imprint numbers, names of all editors and indexer, then, at the bottom of the page:
Body Part No. X 12-41775

So what does this prove? Well it probably proves nothing, but it certainly suggests a general reluctance to declare how old the manual is on the title page – and there is still a fair amount of obfuscation going on out there.