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

But I’m not convinced everybody would be sure what you meant if you referred to an application crashing. So today I was looking for an alternative to “crash” and I came across the following on the LA Times website:

3 injured as LAPD helicopter makes a 'hard landing'
A Los Angeles Police Department helicopter with three people aboard made a "hard landing" in Lancaster today.

Experiencing a “hard landing” is also an expression we’ve heard regularly over the past 12 months in relation to the economy, but I must admit I’d never stopped to think that what they really meant was a crash.

I didn’t have any luck finding a suitable  “crash” alternative via Google, so I looked up the Microsoft Manual of Style where I found the following advice:

“Use fail for disks or stop responding for programs or the operating system. In content for software developers or information technology professionals, crash may be the best word in certain circumstances, but it is well worth avoiding whenever possible.”

So I asked the writer whose documentation I was reviewing to change “crash” to “stop responding”. But I’m not entirely sure. Maybe we should call a spade a spade and a crash a crash.

Now ten/fifteen years ago I would never have done such a thing. When I was working as an editor I would have corrected other people’s appendixes to appendices. But yesterday I wrote appendixes with only the briefest of thoughts as to which version I should choose.

So, when I was taken to task over it, I wondered why I’d made the choice I made.

And I think the answer is that these days I’m trying to be less prissy about my use of English. So I don’t worry about the “thou shalt” linguistic edicts, like “thou shalt not use ‘which’ to introduce a restrictive relative clause” or “thou shalt not begin a sentence with a conjunction” (see my previous sentence for proof of my willingness to break that dumb rule).

My criteria for judging whether what I’ve written is acceptable or not are (in decreasing order of importance):

1. Is it clear what I mean?
2. Is it easy to read?
3. Does it sound like a phrase a human being might actually utter?

Anyway, I thought I should do a little research to find out if I was way off the mark in using “appendixes”. And the results certainly suggest that most people think appendices is the correct form and a lot of people think it’s the only correct form. As is so common with questions of grammar, the use of appendixes even seems to get some people quite angry. I find this hard to fathom since – even if you think it’s wrong – it’s perfectly clear that when someone writes appendixes they mean the plural of appendix. So why get all hot under the collar about it?

A good discussion of the matter can be found … hang on a minute, use of the passive voice, that’s forbidden isn’t it? Let me start that again …

You can find a good discussion of the matter at the WordReference.com Language Forums:

http://forum.wordreference.com/showthread.php?t=57302

Richard Bowen used Google to put together some statistics on how often the two words are used in the UK and the rest of the world. He found that, globally, there’s about a 3:1 ratio in favour of appendices; slightly less if you exclude UK Web pages, but for the UK pages alone the ratio is about 18:1.

http://www.richardbowen.com/appendix-plural-appendices-appendixes.html

So maybe I’ll go back to using appendices. However (yep, that’s another rule broken), I’m comforted to find out that all reputable dictionaries give appendixes as a valid spelling. And I liked the following contribution from mplsray on the WordReference forum:

I'd like to point out that The Century Dictionary of 1895 gives for the plural "appendixes or appendices," so appendixes has been a standard form for a very long time. And, although this might represent his opinion alone and not necessarily that of others of his time, Noah Webster in his 1828 dictionary did not consider appendices to be a naturalized English word, giving the only English plural as appendixes.

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.

What she said (about 24 minutes into the show), while discussing Charlene Li and Josh Bernoff’s book Groundswell, was:

There’s this ladder of involvement in social media. Some people like to write blog entries. Some people only like to comment on blog entries. Some people like to review products. Some people just like to read other people’s reviews and act on that review.

I’m an occasional blogger. Sometimes I’ll post every day, other times months will go by and I don’t post at all (usually when I’m up to my eyeballs at work). In some ways I admire the committed bloggers who write lengthy and well thought out posts every day without fail – and sometimes more than one a day. But I do often wonder why they’re spending so much time and thought on this rather than on their paid employment, or their family.

I’m also an occasional blog reader. I use Feedblitz to mail me posts from lots of blogs, but a lot of the time I just read the summaries and never the whole blog post, or I just delete the email without reading anything. My reason for not reading more blog posts is that I know that if I didn’t ration myself quite strictly I could easily spend several hours a day doing nothing else but reading blogs.

What I’m not is a commenter. I rarely ever comment on blog posts and as for forums, I can’t remember ever answering a question on a forum. And this makes me feel bad for two reasons:

1. I love it when people email me, or add a comment to my blog, with a point about something I’ve said in a post, or on a podcast. However, I rarely ever contact the writers/hosts of the blogs/podcasts I enjoy reading/listening to regularly. So they never know I’m out here, one of an invisible audience, enjoying their work. I really should do something about that!
2. I don’t use forums except as a last resort – at which times they often prove invaluable. I have some questions out in forums at the moment as part of my search for the right online help architecture/method for our new applications. And I remember back in 2002 when I was doing some pretty hairy stuff with RoboHelp, I got a lot of help on the Help forums from people like Rick Stone, Rob Chandler and Char James-Tanny. But I’ve never felt any inclination to become an MVP of anything myself and watch the forums on the lookout for people to help.

Am I just a bad, self-centred person?

Well, no, I don’t think so. For me it’s all about a balance of guilt. I hate spending much time at work doing anything that’s not what I’m being paid to do. I pretty much feel like my company has bought my time from nine to five (with an hour off for lunch) and therefore they own my labour during those hours and if I’m writing a blog post or helping someone on a forum I’m essentially cheating my employers. So I make every effort not to be drawn into this kind of thing, and if it does happen I make sure I work extra hours at the end of the day to make up for it. I think this is the generations-old Calvinistic influence showing through.

And when I’m not in work I feel guilty if I spend too much time blogging or preparing podcasts, because I have a wife and kids who deserve some of my time and attention. So once I’ve done some blogging and some podcasting, that just doesn’t leave much time for anything else that would take me away from my family.

Or maybe I’m over-complicating things. Maybe, as Ann Gentle suggests, it simply that there are some people who mainly just blog, some people who mainly comment and some people who never blog or comment.

About six years ago we got a new manager at work and he had trouble with all the names and acronyms we use. He asked me to put together a Web page of terms and explanations for our intranet. But - without doing any consumer research - I thought I’d go one better and, using a vast amount of home brewed Perl and Javascript, I construct a Glossary site that was essentially a Web front end for a little database. Anyone in the company could add new glossary terms and definitions or edit existing ones. I spent quite a bit of time on it (my own personal time because the guilt thing prevented me from effectively charging the company for my work on this), and the end product was pretty damned good and did things like emailing specified addresses every time a change was made (because I was a little bit worried that a loginless system would tempt someone to go in there are write scurrilous definitions). However, in six years, although I know people (mainly new-starts) refer to it, no one but me ever adds or changes anything. It’s exactly like me and Wikipedia. On average I probably use Wikipedia a few times a week and have done for years. But I’ve never ever edited or added a single thing. I’m not proud of this, I’ve just never felt any desire or obligation to do so.

Communications from DMN:
Talking shop with Anne Gentle

Select either Read or Had read to indicate whether the person read the document themself or had the document read to them.

Word complained (with its squiggly red underlining) about "themself", so I Googled it and came upon a Language Log entry by Geoff Pullum on the use of "they" to refer to a single person, where that person could be either male or female:

So, I've left it as it is. It's not an elegant sentence but it does its job and this is a functional piece of documentation so, in this situation, function rates more highly than form.

However, once in a while I'm reminded that other people might be reading some of this stuff too from time to time. This evening I logged into my WordPress dashboard (not something I often do, because I always post to my blog from Live Writer) and I noticed there was a comment sitting awaiting moderation.

Turns out it was a comment by brian d foy (his preferred style, in case you're wondering), the founder of Perl Mongers, author of Mastering Perl and co-author of Learning Perl and Intermediate Perl. Nice to know that at least one of my posts has had such an esteemed reader.

Oh and by the way, if you're reading this post of the front page of my blog, the way to post a comment is to click the post heading to display it as a single page and then scroll down the the comment form.

"At WhateverCompany we like to produce perfect products. WhateverCompany are committed to perfection and we accept nothing less. Every time WhateverCompany sell a product we hand-check it at least 240 times before shipping it to you."

The problem here is the way the company is treated as a plural: "WhateverCompany are" rather than "WhateverCompany is", and "WhateverCompany sell" rather than "WhateverCompany sells". The thing that prompts people to do this is the feeling that they shouldn't mix a reference to the company as a singular entity in the same sentence as a reference to "we". However, I don't have a problem with this. If you need to say "we" then, obviously, you're referring to yourself and others (plural) who work for the company (singular). So the above should be:

"At WhateverCompany we like to produce perfect products. WhateverCompany is committed to perfection and we accept nothing less. Every time WhateverCompany sells a product we hand-check it at least 240 times before shipping it to you."

There's an interesting discussion about this at Channel 9:

http://channel9.msdn.com/ShowPost.aspx?PostID=205755

http://groups.google.com/group/alt.usage.english/msg/f615e0a4acfa21f1

My favourites are:

arse-
nal

fun-
draiser

lighty-
ears

rear-
ranged

pronoun-
cement

The basic principles I follow are: do task analysis by reading everything available about the feature, reading about the typical users (personas are great for this goal), searching the internet for examples of the features in use, and then interviewing people to fill the gaps in the information available to me.

Next, I start by outlining what topics should be written and if there is a set of templates available I will always use those to the fullest. I guess that my outline-first approach is why the TOC standards are important to me. If I’m editing existing content I keep the users’ goals in mind while editing.

In the list of Latest Essays on Joshua's site I noticed one called A Guide to Writing Well, which isn't aimed at technical writing but, nevertheless, lists lots of useful principles that we should keep in mind while writing technical documents. Here's a few:

• Omit needless words. Write simply and without clutter. Don’t add words for “style.”
• Avoid fancy words.
  “Never use a long word where a short one will do.” (George Orwell)
  “Look for all fancy wordings and get rid of them.” (Jacques Barzun)
  Examples: Assistance (help), facilitate (ease), implement (do), referred to as (called).
• After every sentence, ask yourself what the reader wants to know next.
• Use orthodox spelling, punctuation, and capitalization.
• Use active verbs. Example: “He was seen by Joe” should be “Joe saw him.”
• Keep sentences short.
  “There’s not much to be said about the period except that most writers don’t reach it soon enough.” (Zinsser)
• Remove laborious phrases. Why use “at the present time” instead of “now”?
• Use contractions when they sound natural.
• Write like a person and not like a scientist.

I'm trying to install some Linux software. I looked up the web site of the creators of the software, clicked the Support link and saw the main heading Documentation. This raised my spirits, but only momentarily, then I started to read. Here's how it began. I've replaced the program name with XXXX only because it comes from an open-source project, and I don't really want to shame the hapless volunteer who wrote this:

It doesn't really fill you with any faith that the links will lead you to any useful documentation. And sure enough (with the exception of one fairly decent HowTo, by current Linux standards) the documentation was as dire as the preamble leads you to expect.

The person who wrote the above extract was not a technical writer. I'm guessing (and hoping) English is not his/her first language. I suppose the answer to my question, in open source projects, is that documentation is bad because the project members are all coders, and coders who want to write documentation are very few and far between. Coders who have the necessary skills to write documentation are even rarer. The fact that too often gets overlooked is that technical writing is a specialist profession and is not something that other professionals, like developers or QA engineers, can successfully turn their hand to, when the powers that be realise there isn't any documentation for the customer.

Guy Haas is a technical writer who has some interesting observations about the real-world challenges of writing technical documentation:

http://swexegete.typepad.com/GuysBlog/2004/11/the_dilution_or.html

"Competitive pressure is causing process to be telescoped or even bypassed, and products are being rushed to market with inadequate attention being paid to usability. Interfaces are being tweaked right down to shipping date, and the documentation team often does not get enough time to verify that the final product actuall operates the way the version the team was working with did. And, yes, all too often the doc team finds itself doubling in QA; showing how to use the product uncovering bugs that engineering never spotted."

God, that sounds familiar!