ITauthor

Lots of people get all fretted up about grammar. The Grammar Nazis of this world continue to put the frighteners on the many who are impressed by rules known only by the few. But, since you're reading this, you're probably in the words business, in one way or another, so you may be like many of us who, after going through a phase of flirting with grammar fascism, have learned to relax and enjoy the magnificent beauty and power of the English language, with its huge expressive scope. And, with a little reading, you've probably figured out for yourself that if the greatest writers in the English language don't worry themselves with strict adherence to the rules laid down by the great grammar expert of the day, then there's no reason you should be so hampered. And if linguistics is your thing, Language Log is a great place to go if you're looking for a sane and inquisitive approach to grammar.

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.

In a recent post on the Cherryleaf Technical Authors Blog, Ellis Pratt describes four levels of support that users turn to when they need help using a piece of software.

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.

I'd never heard of ScreenSteps until I got a comment on my previous blog post on putting the technical writer in touch with the software user. Greg DeVore of ScreenSteps pointed me to a post he wrote about getting the people who work the customer help desk to write the documenation. His post includes a section provocatively headed "Technical Publication Departments Are Ill Equipped to Create Software Documentation" in which he writes:

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.

I've often heard technical writers say: "I'd have liked to have had a few more weeks on it. There's some information I didn't manage to get in there and there are parts that I would have like to have restructured ... and some of the input forms got changed at the last moment and I really should have redone the screenshots, and those diagrams were just intended to be Visio roughs, I meant to do a final version in Illustrator ... and really it could probably do with one last round of reviews ..."

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

In my last podcast I talked about a couple of unscripted screencasts I'd recorded for colleagues at work, to show them how to use some Flare extensions I'd created. My question in the podcast was: is something like this (knocked together very quickly) good enough to put in front of paying customers - or potential customers?

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).