But spelling's different. Isn't it?

Surely we can never afford to lower our defences against misspelling? Spelling comes in two flavours: right and wrong. Right? And if you let spelling errors slip through then no one will be able to understand what you're on about. One spelling slip and your credibility crumbles ...  You get the picture.

Well, that's what I've always thought. So I was surprisingly interested in an email Patricia forwarded on to me today. "Surprisingly" because it was one of those pass-it-on emails that used to do the rounds but which, thankfully, you don't get so much any more. Usually they have a list of lame jokes or pictures and at the end they tell you to email it to your friends. Usually I save them straight to my Trash folder. But this one contained some simple editing-type tests (for example, spotting a single N in a block of Ms) and then ended with this:

I cdnuolt blveiee that I cluod aulaclty uesdnatnrd what I was rdanieg. The phaonmneal pweor of the hmuan mnid, aoccdrnig to a rscheearch at Cmabrigde Uinervtisy, it dseno't mtaetr in what oerdr the ltteres in a word are, the olny iproamtnt tihng is that the frsit and last ltteer be in the rghit pclae. The rset can be a taotl mses and you can still raed it whotuit a pboerlm. This is bcuseae the huamn mnid deos not raed ervey lteter by istlef, but the word as a wlohe. Azanmig huh? Yaeh and I awlyas tghuhot slpeling was ipmorantt! If you can raed this forwrad it 

It is amazing how easy it is to read this. And it did make me stop and ask myself: maybe I should lay off the obsessive marking up of every piddling little spelling mistake when I'm sent documents to review. As long as the first and last letter are correct, why worry?

Yeh, right!

I take a liberal, progressive approach to grammar. But I think I'll stick to my hard-line approach to spelling.

I'm not sure I agree with the order Ellis places these in, so this is my reordering (and rewording) of the four levels:

• Ask a friend - usually by instant messaging, maybe by text or email, increasingly via twitter
• Ask the local expert - Ellis calls this the 50-foot guru: "the person within 50 foot of your desk who is more knowledgeable than you"
• Search for help yourself - most of the time this means Googling for it. You might use another search engine, but Google remains the default means of finding information for most computer users
• Call support - this might mean phoning your internal IT helpdesk at work, or it might mean emailing the company that produces the software with a support question and then waiting for a reply

I haven't numbered this list because the order is debatable. Some people don't like admitting they don't know stuff, so they'll always search for themselves before asking someone else. Other people have the attitude: I've got a helpdesk and I'm gonna use it - and they'll pick up the phone to support whenever they get stuck. On the other hand, I suspect people increasingly aren't prepared to wait for a reply to a support call - they've got to have the answer right now, which is usually when a local expert is required. And then for some any excuse is a good excuse to text, tweet or instant message their friends.

These four levels relate particularly to younger users - Ellis says "primarily those under 27", I'm not sure why 27 specifically, but I know what he means. Google first emerged into the public consciousness in 1998, when today's 27 year olds were 15. By that time ICQ and AIM were well established instant messaging platforms. So people around that age and younger have lived their entire adult lives in the Google world, and often they've been using instant messaging as an everyday way of chatting to friends since they were in school. I definitely think people in their late twenties and below are less prepared to invest time digging around researching a subject to find answers than people over 40 (like me).

But even I sometimes don't bother looking up the documentation provided by the software company. In particular, these days I never bother looking up the help systems in Microsoft Office products. Experience has time and time again proved to me that it's simply a waste of time. There's obviously lots of information available from Microsoft - usually when you search the Word or Excel help you get lots of results - but you just spend far too long doing all the leg work, looking through page after page, and often don't find what you're looking for. Go to Google and search from there and you'll usually find the information you need among the hits on the first page of results.

But going back to the four levels of support identified by Ellis Pratt. What about the manual, he asks, where does that fit in? Well, in many cases, that's now one of those things users find by Googling:

many may not recognise it as a manual. It might not have an index, page numbers or a table of contents, but it serves the same function.

The traditional manual is, in most cases, an anachronism now. And traditional ways of creating documentation, based on the way we used to produce printed manuals, are equally anachronistic, even if they're now applied to creating online help. And hey, if most people get their answers about using an application by asking their friends or the local expert, do we even need documentation at all?

Well the answer is yes. Information still needs to be packaged and presented. It's just that this can be done in a different way now, and the information very often gets to the end consumer second or third hand. For a variety of psychological and sociological reasons there are still people who are prepared to invest time learning all about an application. This person becomes the guru. The guru gains some sort of reward from this role and he/she passes on the information to others, who can then share the information with their friends. These second-hand recipients of knowledge are not gurus but they can still, from time to time, supply answers to IMs or tweets asking for help.

Apart from the gurus, the other group that still regularly finds documentation useful is support staff. They'll search a help system on behalf of users who can't be bothered to do so for themselves. And the support staff may even be involved in writing the documentation (this is the ScreenSteps philosophy). Either way, the documentation is the knowledgebase or knowledge repository in which answers to users' questions are to be found, and the support staff can answer a support call with a link to a page in the documentation - typically a specific help topic.

As technical writers we should have no fear that there will be no work for us to do in a few years. Software is going to be around for some time to come and all but the simplest software applications need some sort of user assistance. But it might be that we're not working in a role called "technical writer" - and we almost certainly won't be writing traditional manuals with a title page, table of contents, chapters, appendixes and an index.

But then - despite what many people imagine - I believe most user assistance professionals aren't spending much of their time writing that sort of traditional manual right now anyway.

Tech Pubs have almost no interaction with actual users ... they rarely ask users what they need.

This lack of direct connection with end users means that tech pubs has no idea what information is actually important to their users. They don’t know what questions the users have. They don’t know how best to answer those questions. The end result is software documentation that meets the requirements of “stakeholders” but not users.

Guess what? The stakeholders aren’t going to use the documentation.

It's thought-provoking stuff. I also love an article on the bluemango website entitled "5 Steps to Improving Your Software Documentation". I think I love it because I feel like I wrote it myself. It sums up some of the things I believe in about documenting software - for example: make good use of screenshots and videos and, whatever you do, don't just go through the application screen by screen writing up a description of what's on each screen.

The guys at ScreenSteps also have an interesting take on planning documentation: don't plan.

You can't possibly anticipate every question your users will ask. So don't. Just: write down actual questions people have and then answer them.

This video, while being very much a marketing piece aimed at selling ScreenSteps, contains a lot of very sensible ideas that are worth thinking about:

The don't plan your documentation, just answer users' questions approach sounds great. But it requires a shift in how documentation gets created that will involve a whole restructuring of roles and responsibilities between departments. This might be too much of a leap for some businesses to make.

And what happens if you're working on a new system that hasn't got any users yet? This shouldn't be a problem if you have a truly Agile development process. In this case real live would-be users are getting their hands on beta versions of parts of the system at regular intervals, as it's being developed. The trick for those responsible in creating the documentation has got to be involvement in this process: tapping into the reactions of those early users, soliciting questions from them and using those questions to shape your documentation.

However, for old-style software development (long development cycles against long lists of requirements, followed by an eventual release) it's going to be difficult to use the ScreenSteps approach to come up with an initial help system.

Here's another ScreenSteps quote that echoes a personal mantra of mine:

People don't read documentation, they reference it.

Your users aren’t going to cuddle up by the fire and read your software manual. They are going to read it when they get “stuck” using your software. They are going to read it when they have a question. Make sure that your documentation makes it easy for them to find the answers to their questions.

This is something I repeatedly tell in-house staff (generally, but not exclusively, staff who've worked in the software development business for years) who still equate documentation with printed manuals and who expect technical writers to spend most of their time creating printed books. No! That's not what we're about. We're about helping users to get the most out of the software and we do that in whatever way is most effective - and that's usually not in the form of a printed book.

The bluemango website and their blog (Talking in Pictures) are worth having a browse around. Lots of really sound advice in there. Note: I'm not recommending ScreenSteps as a documentation platform - I've never used it, I just discovered it today - but it definitely looks like a great solution for documenting certain types of software applications.

OK, to be honest, that's me. That's usually what I'm saying - or at least thinking - when it's time to ship the product to customers. And I've always told myself the reason I'm like that is because I'm a perfectionist and the reason I find it difficult to wrap something up - and say "It's good enough. Customers will get more value from getting this documentation now than from waiting a couple of weeks and getting it late" - is because I have such high standards. Turns out I'm probably kidding myself.

The lizard brain

In this video Seth Godin (author of Linchpin: Are You Indispensable?) explains why the resistance to shipping (and by shipping I mean getting stuff finished and despatched/published/released) is just another symptom of our lizard brain at work.

Seth Godin: Quieting the Lizard Brain on Vimeo

Thrash early

Another concept Seth Godin raises in his presentation is one of Steve McConnell's: thrash early. "Thrash at the beginning because thrashing at the beginning is cheap." In this context, "thrashing" means working without making any progress. The expression was coined, I believe, by Frederick Brooks, in The Mythical Man-Month where he described great beasts, long since extinct, that had strayed into a tar pit, thrashing about with all their might but not making any progress to escape their predicament.

In the following diagram McConnell illustrates the situation where a lack of process and planning at the start of a project results in an increase in thrashing, and a decrease in coding progress, the longer you spend on a project.

Diagram from Steve McConnell, Professional Software Development.

When a project has paid too little early attention to the processes it will use, by the end of a project developers feel they are spending all of their time in meetings and correcting defects and little or no time extending the software. They know the project is thrashing. When developers see they are not meeting their deadlines, their survival impulses kick in and they retreat to "solo development mode"—focusing exclusively on their personal deadlines. They withdraw from interactions with managers, customers, testers, technical writers, and the rest of the development team. Project coordination unravels.

Steve McConnell, "The Power of Process", IEEE Computer, May 1998

Without seeing/hearing the screencasts it's not easy to form an opinion, so I thought I'd let you have a look. Let me know what you think. Are you put off by the ums and ahs, and the little mistakes I correct as I go along, or does it lend authenticity to the demo? Personally, I wouldn't mind seeing a demo like this as part of the user assistance for a product. I think the effects that Camtasia lets you add (zooming in and the rotating cube effect) lend a little polish to make up for the ad hoc presentation style. But it's probably not everybody's cup of tea. What do you think?
 

 
Please note:  When I recorded this it was purely meant for internal use within my company. However, I've had a look at it and I'm confident it doesn't give away any corporate IP. It does, however, reveal (if you look closely) that I had to Google to find a solution to a buzzing microphone shortly before starting the recording!  :-)

Alternative larger format video  (you'll need to wait a little while for it to download, but the picture quality is better).

Very few people these days will sit down and read a manual for a new software product. The expectation is that we can install software and start to use it straight away. The younger generation in particular is so comfortable with new technology that they dive in and expect it all to work. They explore fearlessly, and are able to master complex hardware and software concepts effortlessly.

If a user has a problem when they are using the software then they will generally either ask a colleague for help or resort to trying to find the answer in the documentation. Typically, they will “dip into” either a manual or the online help and at this point, if they can’t easily find the exact piece of information they need, they will be frustrated with the software.

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

Rhonda asks “Are humans ‘programmed’ to learn by trial and error and not ‘by the book’?” I think she’s onto something. I suspect that over millions of years of evolution a genetically programmed impulse to play around with things as a way of figuring things out has served the human species extraordinarily well. And so today, if given some software (or hardware), plus a set of instructions telling you how to use it, most of us will ignore the instructions and just try to start using the product.

For example, yesterday, for the first time, I was using the PushOK SVN plugin for Madcap Flare to work on our main online help project. My colleague Graham and I were both working on the same project at the same time. He’s been using the plugin for a while and I was on the phone to him asking him questions and we were working things out, in the style of: “Okay, now I’m going to click on such and such … now see if you can … did that work for you … did you get my changes?” And pretty soon I’d figured out how to do the basic stuff: check out, update, commit. Part of the thing that demanded some trial and error on our part was that the source control menu text within Flare uses Microsoft Visual Source Safe terminology rather than the standard CVS/SVN terminology we’re used to (for example, “check out” means something different).

At one point in proceedings, as we were batting things back and forwards figuring out how it worked, I joked to Graham: “You know what we really should do? We’re technical writers - we really should be looking in the help system!”

Like most people (and I quite often bore people by asking them if/when/how they consult the documentation for the software they use, so I’m pretty sure I’m part of a majority in this respect) I only consult the help system:

• If there’s no local expert around to ask
• If I’m in a situation where I don’t want to ask the local expert because I don’t want to let on I don’t know whatever it is that I don’t know
• If I can’t find the information via Google, or I happen to know the help system will do the business for me (for example, I know I can easily find details of FrameMaker keyboard shortcuts in the application’s online help, but, in contrast, I know there’s little point looking in the online help for Microsoft Word because the search facility brings back so many inappropriate results it’s far quicker just Googling for the information)

And what about printed documentation? (It’s funny, when I talk about “documentation” a lot of people still immediately think of printed books, when in fact the work we produce only rarely ends up being printed. This is probably one of the reasons some folks prefer to talk about “user assistance” – but I find that term confuses most non-IT-professionals.) Well, let’s think … when do I read the paper manual for a software application … emm … never? Since I got broadband access to the internet (back in 2003 I think), I can’t remember ever having consulted a paper manual as a way of finding out how to do something in a software application. And I used to spend a small fortune on computer books. Before my access to the internet was “always on” my home office was cluttered with stacks of computer books and binders full of printouts. In the last few years all of that stuff sat untouched, gathering dust, and it was only towards the end of last year that I finally got round to chucking it out.

But back to Sue Wooley’s article:

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

If you document software applications then you’ve almost certainly had the experience of having to document something when you know you’re writing a whole screed of instructions to compensate for a poor piece of user interface – and it’s obvious that simply moving things around the interface would make this bit of documentation redundant. That’s when documentation can be a bit soul-destroying. You of course petition the developers, log a bug or submit a change request, but in the meantime you have to document what’s there, in the full knowledge that you shouldn’t have to be writing this and the best outcome (for the end user) would result in the deletion of your work.

However, we have to be pragmatic about such things. Sometimes user interface design is just left up to some poor developer who, while he/she may be fantastically clever and a brilliant coder, has no real understanding of usability. And once a bit of poor user interface design slips out into a release it can be very difficult to repair because, unless they’re backed up by complaints from customers, requests for changes to the user interface generally get assigned a low priority. This can be very frustrating, if you’re the one who raised the issue, because some of these things can cause a lot of damage to usability but could be fixed by a little, two-minute change in Visual Studio. The hidden reality, though, is that even a quick two-minute change in Visual Studio can sap QA time by requiring changes to test scripts, updates to automated tests, manual regression testing, and so on. So a two-minute user interface change, that might prevent several hours of work by a technical writer, is often destined never to happen because of the QA cost and the feeling that any additional change carries a risk: so if it ain’t really broke, don’t fix it.

I don’t believe documentation should ever be thought of as “a complete solution in itself” (it should be an integral part of a product), but neither is it always “a backup for deficiencies in the user interface”. The products I work on are usually large, complex systems, where there’s simply too much in there to show it all on one page or in one window ­– with everything achievable within two or three clicks. Some of it just has to be tucked away somewhere to allow other things to be more accessible. As a result, you need some way of helping people find the rarely used pieces of functionality. Unfortunately you just can’t always make complex things simple within an application. Some things need explained. And as for training, well, you can develop and deliver a great training course, but what happens when someone completes a four-day course, covering lots of detail, but then doesn’t need to use a particular bit of the application until six months later?

There are good reasons why documentation is necessary. But, having said that, I’d still maintain that, in reality, for most of us, documentation is the form of assistance that you go to as a last resort, when there’s no other option.

But don’t get down-hearted. If you can create a help system that’s well targeted to provide people with the information they’re realistically going to be looking for, if you can structure it in such a way that people can find the information they need quickly without having to trawl through a list of 20 unordered search hits, if you can write concise and easy-to-read topics that explain just that nugget of information the reader needed to know … then your work is not in vain. Somewhere, some time, you’re going to help someone out. You’ll have avoided some aggravation. You’ll have reduced that day’s global curse count.

And sometimes, no matter how great the help system is, people will choose to ask a human being for help. Why? Well, because we’re social creatures and we’re often just looking for excuses for social interaction. Asking for help with the new IT system (or maybe just bitching about it generally for a while: I mean, the old system worked just fine – now I can’t get anything done!) is a chance to interact with someone, get to know the person at the next desk, chat to the girl in the next booth, make friends or maybe just kill some time.

And anyway, what’s so bad about providing a last resort? Isn’t it good to know we’ve provide people with something they can turn to when all else fails?

This is something we’ve probably all come up against at some point in our careers. Fortunately I work for a company where common sense tends to prevail and a well-reasoned argument, from any source, can be influential. But I know of lots of companies where things are very different. Documentation is often seen as just a cost centre. And when the spreadsheet guys are looking at what’s costing money and what’s winning new business it often looks like documentation is something you could do without. Because – think about it – when did good documentation, by itself, ever win one dollar of new business?

The referee was fantastic!

So, how does a documentation manager prove to the numbers guys that they need to spend money on documentation? It’s not easy. And the reason it’s not easy is partly down to the referee scenario. Think of a great football game (and I’m not talking US-type football here, I’m talking about the football the rest of the world plays). With a great game of football you’re never left talking about the referee at the end of the game. In fact after any game of football you never find yourself talking about the referee unless he did a bad job. You rarely notice the referee if he makes good decisions, lets the game flow, nips trouble in the bud, acts impartially … does his job well. You only notice him when he disallows a perfectly good goal, books the wrong person, consistently favours one team, awards a last-minute penalty when it was a blatant dive, and so on.

It’s the same with documentation. People only start talking about the documentation when it’s incorrect, badly written or absent. With documentation: no news is good news. And this is dangerous. It’s easy to cut the documentation effort because initially no one will notice the difference. The quantity and/or quality of output from the docs team will drop off, but because much of the documentation effort is for new product that’s not going to be released for a while – and even once it is released it won’t be the documentation that customers focus on first – and because the docs team will still endeavour to make sure the high priority work still gets done, it’s going to be a while before this change affects customers. In other words you can get away with it for a while before shit starts to hit fan.

The reverse is, of course, true. It takes a while for cuts in documentation resource to work through and start hurting your customers, but it also takes a while to recover from that situation once the powers that be have decided something needs to be done. In fact, after the problem has been recognised things will continue to nose dive, even after you’ve recruited replacement staff, and even supposing the replacement staff don’t need any training and can magically walk in and start being productive from week one. During this time more and more customers will be hit by the documentation-related problems. A head of steam will build up. Customers will talk amongst themselves about how difficult the software is to use. News might even spread to prospective customers. But by this time the damage that was done was done months before – and there’s no quick fix.

It’s back to the referee scenario. Not only do customers never talk about the documentation unless they’ve got something to complain about, but it’s also true to say that while documentation never won a sale, it is sometimes a contributory factor in a lost sale.

This is the point in proceedings – when you’re doing your best to recover from resource-related documentation problems, but customers are still complaining – that necks are on chopping blocks and axes are poised. And you can bet those necks aren’t the necks of the budget police who wouldn’t let you replace a colleague who left, or wouldn’t grow the docs team in line with the growth in the development team, or who “restructured” the docs team to allow budget to be reallocated to more profitable areas of the business.

Docs are important? Go on then … prove it!

This all sounds very grim. So how do you avoid getting into that mess? You might be convinced that what you do is important – but how do you convince others? How do you prove the value of what you’re paid to produce? How do you answer the question Ivan Walsh got asked: “What metrics do you use to tell if the documents are successful?”

Well I’ve been thinking about this and reading around and there’s surprisingly little out there to help me answer this question. There’s been quite a bit written about what metrics you might use to judge individual technical writers – and maybe measure one technical writer against another – or how you can assess the quality of particular documentation deliverables – for example, the number of comments that were raised during pre-publication review, or the number of documentation bugs raised after publication. But the metrics we’re talking about here are measurements of the value of the documentation effort within your company.

I came across a LinkedIn discussion that mainly concerns the micro-metrics of assessing particular documents or writers (rather than the macro-metrics of assessing the documentation effort itself) but these two quotes, I think, touch upon the bigger picture:

in the final analysis any document is only valuable if it answers the questions the user has so they are not required to make some sort of call to a support person

Keith Oxenrider

A better measure is the readers' view of the documentation. Do they like it? Can they use it to solve their problems? Does the documentation reduce the number of calls to the tech support center? Does the documentation aid the tech support center in quickly resolving client problems?

Dave Gardner

The references to support point to a possible solution.

Donald S Le Vie Jr wrote an interesting and useful article in the December 2000 edition of Intercom (“Documentation Metrics: What Do You Really Want to Measure?”), although he mainly discusses writer-specific metrics that he believes you really shouldn’t bother trying to use – for example, hours per page, pages per hour, documents released per month or per writer, errors per page, percentage of time schedule dates were met, etc. However, he ends the article with some metrics he believes are useful:

• Web-based feedback – e.g. find out what customers want more of, or don’t need, in future versions of documentation
• Customer usability of beta or final versions of documentation. Get them to rate the documentation.
• Team up with Customer Support to make sure it’s recorded when support calls are documentation related.  “Track this information over time to show the decrease in the number of documentation-related calls so you can assign a dollar figure (a quantitative measure) to any metric.”

Le Vie stresses the importance of regularly broadcasting these metrics throughout management.

Conclusion

In the LinkedIn discussion Padric O'Rouark says:

Sell “help” separate and you would find very few buyers.

That’s true, but it’s also misleading. The fact that you wouldn’t pay for something does not mean it has no value. When I buy a bed from Ikea I expect to find instructions on how to assemble it when I get it home. I wouldn’t pay for those instructions separately though. If I was expected to do this I’d just shop elsewhere. As an aside, the poor quality of Ikea’s assembly instructions is one of the things that makes me dislike the company as a whole (that and the fact they try and steer you round the whole store before you get to the checkout, rather than letting you get in, get what you want and get out).

If customer satisfaction is important to a company then the philosophy of doing only as much as you need to do to make a sale, and not one jot more, probably only works if you’re a make-a-quick-buck-and-disappear business, or if you’re competing solely on price and you’re confident customers will accept poor quality products and bad customer service just as long as the price is right.

Customer-facing documentation has no place in a cut-price or fly-by-night business. But in the software business where companies need time to grow and therefore customer retention is important, user assistance is valuable. If you’re trying to sell corporate software then the people with the purchasing power, the decision makers, aren’t the people who are going to be using the software day in, day out. But if you’re in the business for a few years then some of those people who have to use the software in their daily jobs get promoted and end up being decision makers, or at least decision influencers. If you’ve had to struggle for several years using a badly designed bit of software from Company X, that had little or poorly written user assistance, then, later in life, when you get the chance, you’re going to make damned sure you don’t let  Company X inflict any more such pain on any of your staff!

It’s hard to come up with metrics to justify the current size of the docs team, beyond all argument. Bean counters are interested in having more beans to count, so winning new deals and satisfying contracts in order to be paid quickly are things that tend to impress them. In this regard, you could look at the number of documentation requirements within Request For Proposal documents from prospective customers, or you could find out whether documentation was scored as part of customer acceptance tests? 

But other than that, what can you come up with to use as proof of your value to the company that pays your wages? Well, the source of your wages may be the key, because really it’s your customers who pay your wages and they are the only ones who can provide metrics that will convince management of the value of what you’re doing.

I started this piece by suggesting that if you sack tech writers, or reduce the proportion of writers to developers, sooner or later customers will start to suffer. If that’s true then it should be measurable. Keep a record of the number of documentation-related support calls or bad customer feedback mentioned in engineer site visit reports. Have numbers gone up or down over the past six months?

You might never be able to prove that customers are happier because of the work you do, but if you’re able to prove that customers are less annoyed with the products and increasingly able to get on with their business without calling support, then you might just be able to convince people that documentation is valuable.

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.

This is my list of skills, abilities and personality traits that no self-respecting tech writer should be without:

1. Communication skills

So much of the job is about communicating in one way or another – not just writing. Before you ever put metaphorical pen to metaphorical paper you’ve first got to be able to talk to people. You’ve got to be able to understand what people mean – which is not the same as understanding what they’re saying – and then you’ve got to be able to process information, digest it, store it up, remould it, present it, verify it and rework it.

2. Writing skills

You must be able to deliver a high standard of written English. This doesn’t mean you have a vocabulary to rival Anthony Burgess’s or you’ve memorised Fowler’s Modern English Usage. The tech writer's job is to take complicated things and make them easier to understand. Sometimes you’ll do this using diagrams and videos, but mainly you do this in writing. So the key skill here is being able to write in such a way that people can read what you’ve written, just once, and understand what you’re saying.

In technical writing we have little use for nuance and colour, light and shade, or even humour. It’s no good if what you’re trying to explain is open to interpretation, especially if it’s open to misinterpretation! Clarity and simplicity are everything.

Novice tech writers will often try to write in a way that sounds technical. Maybe they’re intimidated by being surrounded by developer gurus speaking a language they find difficult to understand. And they compensate by using technical words and long sentences. So  they’ll say “utilise” when they mean “use”. But the best technical writers are the ones who cut through the jargon, pare down the language and make complex procedures easy to comprehend by breaking them down into easy-to-digest chunks, framed in simple, well-formed English.

The motto of the help author is: "Make the reader feel smart." You want the reader to pull up a help page, find what they need to know,
read it quickly and understand it completely, and go away and do what they need to do, successfully. You want to send them away feeling good about themselves.

One of the keys to being able to do this is knowing your audience. Hopefully, you have a good idea of who your audience are. But most likely you’ll have several audiences. So, another of the writing skills you need is the ability to write at the appropriate level for an identified audience.

3. Attention to detail

It’s those little things that make all the difference. If you’re writing technical manuals for Boeing, or pharmaceutical guides for Pfizer, you will get the detail right because people’s lives depend on it. But even in other sectors, you can’t afford to make little mistakes. One small mistake in a help system and the person who went there looking for help will lose confidence and will probably decide that next time they have a problem there’s no point looking for assistance from the help system.

And it’s often those little things that people often only pick up sub-consciously that make them decide whether something is professional and dependable, or amateurish, and therefore unlikely to be reliable.

4. Interviewing skills

This is very much tied in with Communication Skills but I wanted to pull it out separately because I think it’s very important. By and large when you’re documenting software, you’re assigned to work on something that’s already in production. Other people know about this thing, and you need to find out all about it and quickly. So it’s very important that:

1. you can talk to people
2. that you can identify who you need to talk to
3. you can ask the right questions

You also must be able to listen. The art of the interviewer isn’t just in his clever questions, it’s in his ability to let the other person answer the question.

And you mustn’t waste people’s time. This is a law of software development: there is never enough time. Of all the subject matter experts you need to talk to, developers especially always need to get back to doing their job and you need time to write the documentation. So you can’t afford to waste your time – or theirs – by asking unnecessary questions. Avoid turning the discussion into a general chat, because next time you ask to speak to them they’ll assume it’s going to take a whole chunk out of their morning and you might find they are less willing to talk to you.

In a software company subject matter experts come in all sorts of guises. They’re often the developers, but they can also be product managers, QA engineers, support engineers, maybe (if you're lucky) they might be tame customers, or they might sometimes be your fellow technical writers. You need to be able to identify who the real subject matter expert is, and not just interview the person nearest you, or the person who talks the most.

5. The ability to grasp new information quickly

In my experience developers or subject matter experts are happy to tell you the stuff you need to know, provided you approach them in the right way and you don’t constantly bug them. However, they have no time for people who ask them the same question more than once. If they explain something to you once, they shouldn’t have to go over it again a couple of weeks down the line.

You need to be able to get to grips with how things work, assimilate new information and be able to extrapolate from what you know to make educated guesses which you can then verify with the experts. Good tech writers pretty much always like new stuff.

Part of the fun of being a tech writer is getting to work on new stuff, finding out how it works, and getting to explain it to other people. So the next must-have for a tech writer working in the software business is: 

6. An interest in (and preferably a fascination with) technology in general and software in particular

You have to be technical to a degree, although you don't need to be an expert. It helps to have an understanding of the technology you'll be working with, but it's also good not to have spent too much time in the minute detail of it, because it also really helps if you can think like someone who's never seen the system before. That way you can identify which bits of the system are likely to be difficult for non-technical people to understand. When I'm recruiting tech authors I always look for people who like to find out how things work.

7. The ability to structure information logically

Technical writers often deal with huge amounts of information. Manuals may have hundreds of pages, help systems may have thousands of topics. So you need to be able to analyse, plan and structure your documentation.

You’re going to have to think about how the information you’re supplying will be used, both by the reader (who may be reading this paragraph in isolation from anything else – or they may come to it after reading a couple of hundred pages before it) and in terms of how that information is used by you and your fellow tech writers (for instance, being shared between documents). You possibly also have to consider how the content you supply will be used by other departments within your company.

One of the key concepts in documentation over the past 10 or 15 years has been the idea of single source: writing something once, in one place, and then reusing it in different contexts, in different publications and in different media. For example, you might write a little section of text that will appear in several manuals, several help systems and on your company’s corporate Web site.

8. Patience in problem-solving/troubleshooting

Technical writers are usually working with things that are still in the process of being built. So, often, these things don't work properly, or they get changed without much, or any, warning. Sometimes technical writers get upset when this happens. They get stressed out because the fact that stuff doesn't work makes it hard for them to do their job. And sometimes they might get grumpy and narky because nothing ever seems to go smoothly.

These guys may be good technical writers, but they tend not to love their jobs.

So, if you’re not a technical writer right now but you’re reading this because you’re thinking it might be a job you’d like to have, think about how you’d react to working with immature, first-pass, partially built software. If you think it would annoy you being asked to document something and having to go through repeated attempts at installing, tweaking, uninstalling, reinstalling, reconfiguring, finding the right people to ask for help, figuring out the right questions to ask, try-try-trying again (Robert Bruce style) before you can even start to figure out what you need to document … If that's likely to annoy the hell out of you, then technical writing really isn't for you, because, in my experience, as a tech writer if something you’re working on is broken you usually can't just get someone to fix it for you. Generally you’re going to have to fix it yourself.  So you should have the ability and willingness to install and reinstall software, sometimes time and time again, without picking up the PC and throwing it at the wall when, at the fourth or fifth time of trying, the software still doesn’t work.

Basically, you need to do what you’re documenting. This means that if you’re writing instructions for how to install some software, you need to install the software several times, as you write,  and then when you think you’re finished you have to need (for your own peace of mind) to go through it all again (with your user’s hat on) and install it again, hopefully one last time,  doing only what it says in your instructions, and check that it’s easy to follow – and it works.

9. Graphic design skills

The first documentation manager I ever worked for had this habit of drawing diagrams. Whenever I went to ask him to explain something, he would, as likely as not, reach for pen and paper and start drawing me a diagram. At first this seemed really odd behaviour to me. Documentation was all about words, wasn’t it? Someone who had been a technical writer for years should surely be well able to explain things in words.

But after a while I realised how effective it was as a way of explaining things. And, more than that, I started to suspect my brain worked better in pictures than in words because I found that the habit was rubbing off on me. I realised that whenever I was struggling to get to grips with a concept – or just to piece things together in my head and make connections, and make sense of something – invariably I would feel the urge to sketch the thing out as a diagram.

Technical communicators are increasingly required to produce diagrams, annotated screenshots, videos with accompanying narration or even cartoons and animation. And if you don’t believe me about the cartoons, go and take a look at the work of commoncraft.com. Now, you definitely don’t need to be a designer to be a technical communicator. But I certainly think that you’ll be a better technical communicator if you have some sense of design and a facility with images and diagrams.

10. The ability to review other writers’ work

Technical writers often have to work alone. There are a lot of little software companies out there for whom hiring a full-time tech author is one of the first signs that they are taking the business seriously and thinking about user experience and they’re more than just a band of coders and a sales guy. However, tech writers perform better when two or more of them are working alongside each other, or at least: they’re working in the same organisation. Personally I hate sending my work out into the big wide world without it being checked by a fellow technical writer.

Product managers and project managers,  who review your work, will tell you if you’ve targeted your documentation incorrectly, or if you’re making false assumptions about the end users, and developers will pick up on details if you’re claiming the software does something it doesn’t. But there’s a level of editorial review that a fellow tech writer can give you, that no one else can. Because sometimes you just can’t see an obvious mistake for looking at it, and that’s where a peer review process can save you from looking like an idiot for letting something daft slip through to the customer.

So those are my ten must-haves for tech writers. Do you agree? What would you add to the list? Drop me a comment.

Note: This is an adapted extract from a talk on technical writing that I recorded earlier this month for The Writing Show podcast.

Note: I’ve changed the names.

From: Lesley …
Sent: 10 March 2009 15:00
To: 'Alistair Christie'
Subject: best tool for the job?

Alistair,

I have a requirement to capture a demo the solutions team has been working on – all screen activity and voiceover.  What I want to be able to do is give this to the sales team along with the kit so they can do the demos themselves.  I also want to take this file and have our designers create a flash movie for download from the web site.

I wanted to ask your advice on the best tool to use for this job?  I have looked at GoTo Meeting and Webex Meeting recorders as well as Camtasia.

My slight problem is that Mike is my voiceover person and Ben is my demo click through person – both based in different locations.  This is why I looked at webinar software for recording but it doesn’t look like its straightforward to record voice and clicks on screen in multi locations.

Any advice/hints or tips – I know you have carried out this kind of thing before.

Thanks,
Lesley

Lesley

Here's how I've done this before. You're probably not going to like this! But you asked.

I've never been able to do voice over + what's on screen in one go. One of them always goes wrong. So the system I settled on is as follows:

1) Write the script!

I've tried improvising but you end up with lots of editing to do, so it's quicker to spend the time up front writing a complete script (word for word, not notes).

2) Go through the demo speaking the script and recording what's on screen - but concentrate on getting the screen capture right. I usually don't even bother recording the voice at this stage. That way, if you make a slip with the voice you just stop clicking/moving the mouse until you're ready to pick up the script again, make a note of the time, then continue (i.e. just keep the screen capture rolling). That way you can go and edit out a bit from the screen capture.

3) When you've captured the screen stuff OK and you're happy with it, go into Camtasia and chop out the bits you noted down. When you do this you've got to go through that bit of the script so that you make sure you haven't cut too much out.

4) In Camtasia, generate a video (Flash or AVI or whatever - doesn't matter at this stage).

5) Using sound recording software (like Audacity, which if free), record yourself speaking through the script while watching the video. You generally have to do this a few times until you get the timing right.

6) Save the recording as a .wav or .mp3.

7) Back in Camtasia, import the sound recording and drag it onto the time line of the video.

8) Play through the whole thing and make sure the sound and video match up. Usually at this stage you need to do some fine tuning, but Camtasia allows you to pause or cut the video and/or pause or cut the sound recording, so it's pretty easy to get it all spot on

9) Output the final demo video.

Camtasia has a huge variety of output formats, resolutions, styles - including .wmv for showing in Windows Media Player, .m4v or .mov for iTunes, or a .swf (Flash) file nicely embedded in a Web page. If you want you can easily grab the Flash file from this page and stick it in another page (e.g. on the company Web site).

Technically there's nothing to it, but if you want to produce something half decent it will take lots of time and patience. The one I did for … last year took 3 full days to produce.

As for folks being in separate places, that shouldn't be difficult, Mike can be on the phone speaking the script, looking at what Ben's doing on screen (Acrobat ConnectNow is good for this - like WebEx but free), while Ben records what he's doing in Camtasia. Ben can then put together the video (without sound) and send this to Mike for him to record the voice over. When Mike's got this just right he can send the sound file back to Ben and Ben can finish it off.

Job's a good un!

Alistair

http://dmn.podbean.com/2008/09/29/talking-shop-with-anne-gentle/

As a result of realising this podcast exists, I’ve now added it to my Technical Writers’ Podcast Mashup RSS feed:

  http://feeds2.feedburner.com/techwriterpodcasts

In this podcast, I give a quick overview of the bid writing process, I describe some of the reasons why technical writers are an obvious choice to join a bid team and I give a few tips for surviving the bid writing process and submitting a completed bid on time.

Extract from the podcast:

As a technical writer asked, or told, to work on a bid, you may feel about it much the same way a developer feels when he's told he has to document the product or features he's just coded. You're naturally inclined to feel like this is not what you signed up for, and that there are lots of better, more important, more appropriate, more interesting things you should be doing.

However, I believe you should try not to feel like this, because it's an important job and it's one that you can probably do better than anyone else, so it's really a chance for you to shine. If you want to raise your profile within the company, you won't get a much better chance of doing so as a tech writer than working on a big contract-winning bid.

Tips:

1. If possible, don't tell people the submission date. If you let on it's a week on Friday, you might not get anything back for editing until a week on Thursday.

2. Get yourself organised. You need a system for tracking the progress of a large bid. Knowing exactly where you are with the bid, even if you're a little behind schedule, will help to keep the stress levels down.

3. Arrange little rewards for yourself and for everyone working on the bid. If you can make the job less of a chore you'll get better results. Bring in cakes when a major section is complete and make plans to go out for a night out the day the bid is submitted.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

In this podcast I explain why I think release notes are important. I talk about what customers expect to find in release notes. And I step through a typical release notes template.

Here's the text of this podcast:

I seem to have been spending a lot of time recently working on release notes. And because I haven’t written release notes for a few years I’ve had to think quite a lot about the purpose of them. Specifically: 

• What’s the point of them?
• How are they used?
• Who uses them?
• What do people need to get out of release notes?

All these questions have been buzzing around my head recently, so that’s the subject for this podcast: Release Notes.

Now you might be thinking that this isn’t relevant to you, and in your current job maybe it’s not, but believe me release notes are important in some positions and you never know, at some point, you may be looking for a position elsewhere, or you might want to work as a contract technical writer in which case, sooner or later, you’ll be working somewhere where you need to know about release notes.

The first thing I’ve realized is that, out of all the documentation I produce, the release notes are the only thing that I can guarantee will get read. And they’re not just read – they’re positively scrutinized in a way that most documentation isn’t, because it’s just there for when it’s needed and as long as the customer knows that it is there then that’s generally enough. So, for instance, the customer might have sign-off requirements that stipulate that they won’t accept the software (and pay for it) unless it has: online help, a user guide, an install guide and a configuration manual, or whatever. But they won’t read these through – they just want to check them off.

The release notes are another matter. When we release a new version of our software we want our existing customers to install it – maybe because it’s going to fix some issue they’ve been having, but maybe just because we can offer better support across all our customers if they’re all on the same release – at any rate we want to avoid too wide a range of releases being in use out there. And we really want to avoid customers sticking on an old release and not budging. So an important point to be aware of is that the release notes should spell out for the customer the incentive, or compelling reason, for upgrading. On the flip side, a lack of any incentive or compelling reason in the release notes may provide customers with their justification for not upgrading.

I mentioned before that release notes are read carefully. In all my years as a technical writer and documentation manager I’ve had very little spontaneous feedback from customers. Customers are usually happy to comment on the documentation if you ask them nicely and get them at the right moment. Face to face they’ll typically struggle to give you an immediate response because it’s probably something they really haven’t thought much about. This is a good sign. Documentation is like a referee at a football game, or the umpire in tennis. If you notice him it’s usually because he’s doing a bad job. So, typically, the person you ask for feedback will delegate the job to someone who uses the software more frequently and – in due course - you’ll get some comments back. But through all my years writing manuals and creating user assistance the No.1 subject for documentation-related comments from customers is the content of the release notes.

Where I work right now our standard release notes document has been largely shaped by one of our main customers. Again: this is a good thing. If you’ve got customers taking an interest in your products and telling you what they want then you’re lucky. They’re doing some of your work for you.

You’re initial reaction, when you get a customer saying: “We need rollback instructions” or “We need to know exactly which minor release versions of the such-and-such server-side software is compatible” – you’re initial reaction might be: “They’re trying to tell me how to do my job. I'm the technical writer. I don’t go telling them how to do their job.”

This is the wrong approach. This is like sending a document out for review and then taking umbrage because your reviewers actually picked you up on some of the things you wrote. Just because you didn’t ask your customers for their opinion doesn’t mean you shouldn’t be grateful to get it.

And whereas when you get review comments back, you take a view on which comments you’re going to act on and which of the suggested changes you’re going to make – with comments from customers, you better have a very good reason for not acting on them. If you take the view that you know better than your customers then you really need to stop and think about who’s paying your wages.

So, why do customers care about release notes?

Well, maybe your customers don’t. It really depends what sector you’re working in and what type of product you’re documenting, and how those products are sold.

In my case, our customers are generally large organizations running mission-critical systems. Our software is integrated into the customer’s enterprise-wide network and in many cases the software is operational 24/7, 365 days a year – so an upgrade to the software that may result in any downtime for the system is a big deal. Likewise there are training issues for any new functionality or changes to the interface. And there’s generally acceptance testing, where a sandboxed installation of the new release is tested before a decision is made whether or not to upgrade.

Of course your customers may not be so interested in release notes. For consumer products, for instance, your customers may never bother to look at the release notes – they may not know where to find them, or care less – they might not have a clue what release notes are. But the chances are that – even in this scenario - release notes do still exist, and someone needs them even if your customers generally don’t. In some organizations the release notes may be more for internal consumption than for external reading. Your support partners or MVPs probably want to see release notes and developers who have recently been moved into the product team for this product might want to read up on what’s been happening with the product recently.

Technical writers also find release notes very useful. Let’s imagine that the tech writing resource is short. Lots of developers churning out lots of code, day in day out, making lots of new product and changes to the existing products, and not enough people documenting all that new stuff. Imagine this state of affairs persists and a product has a series of releases where the core documentation (the Getting Started Guide, the online help, the admin manual) aren’t updated. You just didn’t have the staff to update that material. Nevertheless, when times get tight and you’re cutting back on everything that can be cut back on, the last thing you stop doing is writing release notes. If you release without release notes you may as well pack up and go home. But in fact you’ve probably gone already. You’re probably working somewhere else by that point.

Anyway, let’s suppose you’ve been prioritising products A, B and C – and, as a result, products X, Y and Z haven’t had any documentation done through a handful of releases other than the release notes. And then things ease off on A, B, C and you can spend some time on X, Y, Z. The first thing, as a technical writer, that you’d go to, to give you a good idea of what had not been documented through those releases would be the release notes.

All the new functionality and important changes will be listed in the release notes. So if you’re on release 7.5 now and the last update to the online help was done for release 7.2, you can pull up the release notes for 7.3 through 7.5 and, in double-quick time, you’ve got all the details you need to scope out the work you need to do to get the help system bang up to date again.

And believe me, when you pull up those release notes and you find they’ve been written thoroughly, and you can be confident that all the changes and new stuff did make it into the release notes, it's such a relief, because it can save you many, many hours – if not days –

of effort.

But this talk is really about the scenario I’m most familiar with, where your customers are large organizations or corporations for whom their IT system is a critical part of their operations. There are a range of reasons why release notes are important to such customers – but let’s just look at the three I touched on earlier:

1. They provide details on what’s involved in the upgrade process

2. They tell the customer what changes have been made to the software

3. They inform the customer’s testing regime

So, taking each of these in turn:

No.1 – What’s involved in upgrading the existing system?

They’ll be looking for an indication of the complexity of this task to give them an idea of any downtime that’ll be needed, whether data conversion is involved (which will play a large role in the

risk assessment they carry out for the upgrade). They need to figure out how many staff will be involved in performing the upgrade. They’ll need to cost the work and schedule it. The schedule will involve booking time from the appropriate people and working out the best time to carry out the work, allowing for the possibility of a problem occurring and having to back out of the upgrade.

For that reason they’ll expect the release notes to say something about installation (that is first-time installation), and more importantly upgrade (with details that specifically mention upgrading from the release they are currently running, so that they have confidence that the supplier has tested the upgrade path from their existing release to the current release).

And they’ll want to see roll-back instructions because they want to know that the supplier has thought about how the customer can get back to the existing version of the system if the upgrade to the new release fails.

This might sound like a lot of stuff but of course all of these things may be very simple. Chances are that installation or upgrade just involves taking a backup and then double-clicking an installer file, and rolling back might just be a case of moving the backup back into place. These things needn’t be complex, but they still need to be mentioned.

Typically, release notes have a standard set of sections and those sections appear in every set of release notes, even if there’s nothing to say. For example, you may have a New in this Release section, but it’s a minor bug fix release, so there’s nothing new. In that case you’d still have the New in this Release section, but it just says something like: “No new functionality has been added in this maintenance release.” Doesn’t sound great. But at least that way everyone’s clear.

However, sometimes the installation or upgrade process is complex. In this case these procedures may require a separate document (such as an Upgrade Guide or an Installation Guide, or both). Again, if your release notes normally have Upgrade and Installation sections, don’t leave these out because upgrade and installation are covered in separate documents. Keep the sections but just give them a one-liner pointing the reader to the other documents.

No.2 – What changes have been made to the software?

So the customer’s going to be looking for answers to the following questions:

• Have the issues I reported been fixed?
• What’s the scale of change?

  If there are significant changes, and particularly changes to the UI, or completely new areas of functionality then that’s going to impact my users and I may have to think about training – which means cost and inconvenience.

• Given what’s been fixed (or not fixed) – and the likely difficulty (or ease) of the upgrade, and any retraining requirements – on balance is it worth the trouble of upgrading?
• Do the list of changes indicate that the product being actively developed, or is the supplier just tinkering around the edges? In which case maybe I should be looking for an alternative solution.

This is the sort of information the release notes should be providing.

Point No.3 – What sort of acceptance testing needs to be done by the customer? 

So, assuming they haven’t (as a result of reading the release notes) changed their minds about upgrading, they’ll want to stick the software on a test environment and check it out. So they need to know what that environment should be (are there any changes there from the previous system?) and then, once it’s up and running, what do they test for?

Well the obvious things they’re going to test for are the new things: do they work as advertised and are they easy to use? And the fixed stuff: is it really fixed?

So, as a customer, I’d be hoping that the description of new features and fixed bugs was clear enough to allow me to try out those new features and at least spot-check the fixed bugs by trying to reproduce them. But if the bug’s not clearly described, there’s no way you’re going to be able to do that.

So I guess it's really all about giving the customer confidence. For IT managers in charge of enterprise-side software systems, new releases carry with them the fear of the unknown. If the current release is buggy they’ll be worried about the possibility of installing something that could have even more bugs. If the current release is nice and stable, and everything’s been running smoothly, then you could forgive them for adopting an attitude of: if it ain’t broke, don’t fix it.

The bottom line is you want to help them out. By the time they read the release notes they’ve agreed to upgrade (with various conditions) so you really want them to read your release notes and feel like they’re doing the right thing!

What about the format of release notes?

We produce our release notes as PDFs. We write the document in Microsoft Word and then generate the PDF after the Release Authorisation Meeting once the software has been signed off for release and the release notes have been checked and discussed in the meeting. Often the list of Known Issues in the release notes is pulled up on screen during this meeting and reviewed there and then in terms of:

• Are these the right issues to be declaring?
• Can we release with these bugs in the software?

We use Word for writing the release notes just because it’s not always the technical writers who write the release notes, so we have a Word template that anyone can use to write a set of release notes, and often reviewers want to mark their comments within the Word document (we don’t have Acrobat Professional - so people don’t have the ability to mark up or add comments to PDFs). But really I don’t think it matters so much what you use to write your release notes, or the format of the document you give to customers. A lot of companies use Web pages and that’s good – and it’s perhaps a way we’ll go in the future.

When I joined the company I work for now we used to send some release notes out as plain text files. And there’s nothing very wrong about that, except that a nicely formatted document is easier to read and looks much more professional. As I said before, the release notes are partly about inspiring confidence, and for me plain text release notes gives the impression this is bedroom coder software.

Publishing the release notes as Web pages and hosting them on your own Web site has the benefit that customers and staff always know where they are and can refer to them at any time. For example, when there’s a new release a customer might want to review the previous release notes particularly if they’ve missed some releases, and they want to reassess all the features and fixes in the releases they skipped as well as in the new release. It also shows prospective customers that you’ve got the balls to publish the release notes, complete with known issues, so it should help to show them that you’ve got nothing to hide.

Who writes the release notes?

I’m a technical writer, most people listening to this podcast are technical writers, so, guess what?

It’s often a technical writer who writes the release notes. But not always. Often the technical writer does an editing job on the release notes, and they’re actually written by the development project manager or lead developer. I’d say that’s’ the best way of doing things because the project manager knows what’s in this release, he or she knows what the keys themes of the release are, what the important resolved and unresolved issues are. And generally, the project manager has all the information that needs to go in the release notes.

I take every opportunity of reminding people where I work that no customer-facing documentation

should leave the building without it being edited by a technical writer. And, so often in the case, where the project manager, or senior developer, has written the first draft of the release notes, the technical writer gets to play the part of the customer - reading through the document and trying to think of what the typical customer will be looking for, or will need, from the document, and editing it accordingly.

But all too often, unfortunately, release comes along and the project manager has done nothing about the release notes, maybe they’ve dropped off the release checklist, or maybe the technical writer is just expected to produce the release notes. In this case:

• How do you start writing release notes?
• How do you find the information you need?
• How do you decide which issues to declare?

Well the starting point is typically the previous release notes document. Unless this is a new product, you’d typically pull up the previous document, rename it, and start editing it. Even for a new product I often start by pulling up the release notes for a similar product. We do have a template for release notes. But invariably, I find it easier to use an existing document as my starting point.

Finding the information to go in the document should also be very straightforward, with the project manager being your first port of call. He or she may not want to write the document but, as the project manager, they’re still the authority on the release, and they should know what they want to go in the document, or at least be able to give you the headline stuff and an overview of the type of other stuff you should be looking to put in there.

If you have a project management system, it should also provide you with a list of things that need to be included as new features or fixed bugs. The other main source of information will be your bug tracking system.

What do you put in there? What do you leave out?

These questions are particularly relevant for known issues (“bugs” to you and me) that either customers have reported, or which have been discovered in house, by QA engineers, technical writers, professional services staff and so on.

If you have a small piece of software that’s fairly new, and you have a small customer base, then the product manager might want everything to be declared in the release notes. But what about if you have a big, complex software solution that might have been around for years evolving steadily, or in leaps and bounds, through each release? In this situation you couldn’t possibly list all the bugs ever reported and not fixed, because the reality of software development is that there are always bugs and you never fix them all.

Some bugs simply aren’t worth fixing. You could put half a dozen developers to work fixing all the bugs, including the ones introduced as a result of fixes to other bugs, and they could spend months and months fixing those bugs, but from the customer’s point of view – the customer would see nothing happening to the product, release after release would come out with fixes to bugs the customer wasn’t bothered about, but no new functionality.

So what always happens is that bugs get prioritized. Bugs that damage data, or amount to security issues, or which prevent you using the product as intended get a high priority. Bugs that customers raise get a high priority, especially if it’s a big customer or a customer who’s about to buy something, or an influential customer who you need to keep happy. But there are always other bugs that get spotted in house, which occur rarely, in very specific conditions, or in remote corners of the application, and if these bugs don’t really inconvenience users, and nothing bad happens as a result of the bug, then this kind of bug will be given a low priority. And if there are other, higher priority bugs to fix and customer change requests to implement, then the low priority bugs may never be fixed.

Over the years these minor bugs inevitably mount up and if you list them all in the release notes then:

a) It’s misleading because it gives the impression the software is full of bugs, when in reality most customer would never find the vast majority of those bugs. It’s also misleading because it suggests you’re going to fix these bugs and in reality you’re not. Some of them will simply never be fixed. Because the business we’re in is all about bringing value to the customer, and there’s very little value for the customer in fixing those minor bugs at the expense of building in new functionality, or new products.

b) If you list all the bugs then it becomes difficult to see the important issues for the forest of minor ones. As I said before, customers generally want to check for the issues they’ve reported and they want to know about the risk of installing the software.

So, generally you should be declaring:

• All issues raised by customers.
• Any other high priority issues that customer need to know about.

The latter are the kind of thing you’d be embarrassed if your customers discovered and you hadn’t already found during QA testing. These are things that weren’t severe enough to prevent the software being released, but will definitely be fixed in a future release.

Rule of thumb should be that you never declare known issues in the release notes that will just sit in the known issues list for release after release and will never be fixed, because all the important bugs will be fixed and only the important bugs should be listed.

An eagle-eyed technical writer may have reported a spelling mistake in an error message,

but that shouldn’t take up space in the release notes.

And that leads to another point about the Known Issues list. The only way an issue can be removed from this list is if it is fixed. So issue 1201 gets listed as a Known Issue in the release notes for release 2.3.1. It’s not the highest priority issue, so release 2.3.2 comes along and the issue hasn’t been resolved, so it stays in the list. But after that it is fixed. So at release 2.3.3 it moves into the Issues Addressed (or Fixed in this Release) list. And then at 2.3.4 it disappears altogether.

This is a point you should bear in mind. If you put a low priority bug in the release notes, it might have to stay there for a long time, through numerous releases.

Who reviews the release notes?

So the release notes have been written. They’ve been edited. What happens next? Who reviews the release notes?

In my experience release notes are among the easier documents to get reviewed. People generally do care what’s in the release notes.

So apart from peer review by another technical writer, the release notes should be reviewed by:

• the product manager
• the development project manager or lead developer
• the release manager, if you have such a role
• at least one Support engineer
• at least one Professional Services representative
• the Customer Services manager responsible for delivering this release to customers

Practice where I work currently is that we try to get the release notes out to everyone at least a couple of days before the Release Authorisation Meeting, get the review comments back in, collate the comments, and get everyone a revised copy of the release notes before they attend the meeting.

Generally, there are some further changes raised during the meeting and these get implemented immediately after the meeting, after which the PDF is generated, gets a final check and sign off and is then shipped with the software.

The release notes template

So finally, it might be useful to describe a typical release notes document. Release notes vary, from product to product, with extra sections being added as necessary. But these are the standard sections in a release notes template:

Page 1: title page – Product name, document name (i.e. Release Notes), release number (e.g. Release 2.1), company name and address, contact numbers and web site address.

Page 2: title verso – publication date, copyright information and document version number (we have a code that tells us the names of the author and editor and the date the PDF was generated).

Page 3: Contents page

Then subsequent pages contain:

• Overview or Scope – This is simply a brief overview of what the document covers.
• System requirements – supported platforms (e.g. Windows XP with SP3, Vista with SP1, Red Hat Enterprise Linux 5, Solaris, whatever …), required third-party software (e.g. you might need to have Word 2003 or Adobe Acrobat 8 installed for some features to work)
• Features added – This is a description of all the brand new good stuff that’s gone into this release. This needs to be a functional, accurate description, but it also needs to be a bit of a marketing job to tell customer how this release improves the product – so you should describe the benefits of each new feature.
• Issues addressed – This is a list of fixed bugs (but we call them issues because “bug” is a techie word and “issues” sounds less like these are things we screwed up). In our case, we do this list as a table and each issue has the reference number our Support department gave the customer (this is a reference number for a case in the SalesForce system where we log customer information), plus we have the internal reference number from our bug-tracking system. The description of the issue is as brief as possible – just enough for the customer who reported the bug to be able to confirm that the reference number matches the problem they reported.
• Known issues – This is also a table with one row per issue – each issue having a customer ref, a Bugzilla ref and a description of the problem. The description should be as brief as possible and should give a context where appropriate – for example, if the issue only occurs when the moon is full and there’s a southerly wind, then you should include this information otherwise customers will assume the bug happens to all users all the time. Where possible you should include a workaround, but don’t include a contrived workaround for the sake of it – sometimes there just is no workaround and it’s annoying for customers if you treat them like idiots by suggesting a workaround that’s clearly not a real option for them.
• Installation – This is for customers who are new to the product. This section might just tell them to double-click the .exe file – or might refer them to a separate document if there’s a complex installation procedure.
• Upgrading – For customers who already use the product. Again this section might be very simple, but might involve some data conversion procedures, or it might include steps for backing up the existing installation prior to doing the upgrade.
• Rolling back to the previous release – What happens if you attempt an upgrade and it all goes horribly wrong – or you just don’t like the new version and decide to go back to the old system?
• Related documents – This is just a list of any other useful documents – for example, an installation guide, a configuration guide, admin guide, FAQs, or whatever.
• Release details – This is on the final page of the release notes and it’s just a little table containing a quick-glance summary of:

  – the application name

  – the release number

  – the build number

  – the build date

  – the supported database version (if this is client-side software).

Finally you might be required to include additional standard text in your release notes, such as:

• Disclaimers
• A copy of the GPL
• An anti-piracy warning and so on.

   

Top tips for producing release notes

Release Notes are often overlooked, or given to the junior technical writer to work on, but they’re a very important piece of documentation and worth getting right.

My top tips for producing release notes are:

1. Get the project manager (or lead developer) to write the release notes. If they don’t write, or at least draft, the release notes, you’re only going to have to pick their brains, so it’s much more efficient all round if they do the initial work, and you do an editorial job.
2. Use a template with standard sections.
3. Fix a procedure and get it agreed with all parties. Once you’ve done this you can use a checklist to make sure you cover all stages, include the appropriate information, and get the document reviewed by the right people.

I hope you’ve found this podcast useful. If I’ve left anything out, or if you disagree with what I’ve said, or if you have any questions, then please add a comment in the form below.

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

Say you make a change to a topic and you just want to check quickly that it'll work correctly within the compiled help. For example, the topic might reference a JavaScript file that only works in the context of the Help Viewer, so if you just open the topic in a browser the page doesn't look and/or behave like it does within the help system. So you need to check it in the help system, but you don't want to recompile the help system.

The solution is simple. Just open the existing .chm file, right-click the title bar and choose Jump to URL.

In the Jump to URL dialog box, enter the path to the file you want to test:
 

Click OK.

The topic is displayed in the Help Viewer just as if you compiled it in there.

On a recent StackOverflow podcast, a listener asked the presenters for tips on how to "get in the zone" as a programmer. We take up the theme here and talk about how you can get yourself in the writing zone as a technical writer, and we try to identify the things that prevent you from getting in the zone.

Preparation

Do adequate research up front so that by the time you you start writing you can continue writing without having to keep stopping to check things out because you know your subject.

Avoid distractions: Email

Resist reading your emails throughout the day, as they arrive. If you *do* read your emails, resist the temptation to act on them there and then. Make a note of things you need to do and come back to these things later.

Avoid distractions: The Internet

One Web page draws you to another and another and another, and before you know it half an hour has passed. Steel yourself to stay off the Internet. When you *do* need to visit a Web page, imagine you're back in the days of expensive metered dial-up, when using the Internet was a case of getting on there, getting was you needed as quickly as possible and getting off again. Just imagine you're paying from your own pay packet for each minute you spend on the Web during work hours.

Listen to the right kind of music

This one's a personal thing. I can mentally turn down the volume on conversations going on around me in the office, so that I'm not distracted from what I'm working on, until someone says my name a couple of times. But you might be the kind of person who finds that difficult and naturally can't help but listen to whatever chat is within earshot. If that's the case you might find it useful to put headphones on and listen to music. But it has to be the right kind of music. If you play songs you'll be listening to the lyrics. If you play music you really like, you'll be busy enjoying the music rather than writing. If you play mood music, you've got to make sure it's the right kind of mood: if it's too reflective or sombre it may bring you down. Graham recommends film scores (e.g. the music from the Transformers movie). I rarely listen to music while I'm trying to work because I tend to find the music gets top priority in my mind and I find time will pass and I suddenly realise I've just been listening and not working. One time the folks around me were chatting a lot, and too loud to tune out, so I listened to some free background music I'd downloaded for the backing track of a video demo I'd produced. The music was very innocuous and repetitive and I played it on a loop. That worked pretty well. I also sometimes use headphones with no sound just as a visual "don't talk to me" sign. That's pretty effective if you need to get on with work and don't have time for chatting.

The "meh" effect

It's Monday morning and the weekend just wasn't long enough, or you had a bad night's sleep, or you had an awful commute to work. You need to find something to raise your spirits, shake off those negative feelings and get yourself into a frame of mind where you want to do some good work. How you do this is going to depend on your own psychological traits and what works best for you. So if rewards work for you, you could promise yourself a reward of some sort if you get a realistically achievable amount of work done - just to get you going. For example: if I write 2 decent-sized help topics by lunchtime I'll buy myself a slice of chocolate cake to have with my coffee at lunch.

Meetings

Avoid attending meetings that you don't really need to attend. Can someone else who's going to the meeting report back to you with a highlights version of what was discussed? If you need to go along to the meeting can you be called into it just the bits that directly concern you and then duck out when the discussion moves on? If not, and it's a long meeting, can you take in a laptop and do some work (even just catching up on email) while other attendees are discussing issues that don't concern you? For all meetings, make sure they're time boxed. If the meeting is scheduled from 2 till 3, make sure everyone knows that you've got something you need to do at 3. If you can, time-box contributions within meetings. We use a little application called Dinner Timer [LINK AND PIC] that gives the person raising an issue a set time to discuss that issue. It counts down on the screen and sounds an alarm at the end of the allotted time, at which point the meeting moves on to the next issue.

When you're in the zone, stick with it

Working late when things aren't going and you're having an unproductive day isn't particularly smart - better just to go home and tell yourself you'll get in early the next day. Go home, relax, have a nice meal, have a long soak in the bath, get a good night's sleep. But when you *are* in the writing zone, hang on in there and make the most of it.

Give yourself realistic deadlines

Nobody works efficiently if they're working under stress. If you make your own schedules, try to make sure the dates are achievable. If someone else gives you a schedule, don't agree to dates unless they're achievable. It's going to be less stress overall if you have a bit of aggravation up front renegotiating a schedule that has a better chance of success.

Don't expect to always be able to get in the zone

When you're working on a larger project (e.g. an iteration of development on a new product) you have more chance of getting in the writing zone and having really productive days. But for some types of documentation work that's just not going to happen.

Recommended applications

Adobe Lightroom: http://www.adobe.com/products/photoshoplightroom/
 
Microsoft PhotoSynth: http://photosynth.net

Foldersizes: http://www.foldersizes.com

Recommended podcasts

Steven Fry's Podgrams

Right now the RSS feed for this podcast is broken, but here's a link to Steven Fry's Web site:
http://www.stephenfry.com/media/

A Way With Words

KPBS Radio in San Diego
http://www.waywordradio.org
http://feeds.waywordradio.org/awwwpodcast

The music I play at the beginning and end of the show is by Amplifico. You can hear more of their music at Podshow.

So we have a legacy help system (which I created about six years ago and the content of which is mainly still my work) which is supplemented by context-sensitive help (CSH) for each solution. One of my tasks for the coming months is to make sure that the topics in the core help system work equally well in the context of each solution. The tricky bit is that these solutions are designed to be integrated, so while one customer may only have Solution B, another customer may have Solutions A, B and C all integrated together within the same system, with some of their users only getting access to one solution, but others seeing all three. And the help topics need to allow for this without: a) requiring any coding (because no development effort is available for user assistance) or b) turning into a maintenance nightmare by creating a web of conditional behaviour.

But thinking about how this might be done led me to consider how important this core help system is. And in my opinion, from the user's point of view, the importance of assistance is largely measured in relation to how immediate it is. This is, of course, balanced by how useful it is and the nature of the assistance they need, but number of clicks away from where I am now is a big factor. So it shapes up like so:

1. What's in the user interface (labelling and messages).

2. What the user sees first when they click Help.

3. What they see next.

4. If they're still looking, what they see next.

Tech writers don't get involved enough with point 1 (Graham and I were just discussing this yesterday). It's something we could really help out with but are rarely asked to contribute to. Now I'm not saying that a good tech writer is necessarily a good usability analyst, but I know from experience that we're often more sensitive to usability than the programmers who often get left to write user interface text.

Point 2 might be a CSH topic with the information the user needs, but sometimes (e.g. when there are lots of things you might be doing on that particular dialog box or form) it's not possible to cover all the bases in a short, snappy help topic, so you need to use a landing page topic with questions that will branch out into information topics.

Point 3 is either a topic within the help system (if 2 was a CSH topic) or a CSH topic (if 2 was a landing page).

Point 4  is a topic within the help system, and because it's so far removed from what the user was looking at, he/she may never get here. Help is all about getting an answer and getting on with what you were doing as quickly as possible. Nobody but a really desperate user - or a tech writer - browses a help system.

So I think we need to really focus our attention on the context-sensitive help: the CSH information topics and any landing page topics we need to use. Yes, we should try to make the core help system as comprehensive in its coverage as we think genuinely represents value for money and a good use of our time/effort, but I believe we should only do this after we're happy that we've made a really good job of the CSH.

I guess it's the tyranny of the majority again. We're spending a lot of effort crafting really well targeted, clear, concise and correct topics for the majority of users who never get past one or maybe two clicks into the help. And inevitably, in doing so, we're going to have to sacrifice some of the requirements of the minority of users who occasionally go looking for information in the core help system. For them, I believe, we should concentrate in getting the information in there for them. It might not be pretty. We might not have spent so long crafting it to be easy to digest. But it's better to have information in there that you have to read twice to work out what it means, than not to have the information in there at all. We can comfort ourselves, perhaps, with the thought that users who are prepared to go digging in the help system may be more capable of understanding information that might be a little bit raw.

Here's another, slicker version for Google Docs. This is the one I came across first because Google use it on the front page of Google Docs. It's style is very Google like - simple, no frills - which made me think it was an in-house production from Google.

Note that although it's slicker it's not more effective because of that. It's the method of communication that's the important thing here, not the adeptness of the execution.

There's a stack of videos on all sorts of things like blogs and RSS and social media. You can find them on YouTube or at http://www.commoncraft.com/. One of my favourite is the one on podcasting. Next time someone asks me what podcasting is, I'm going to send them a link to this video: