ITauthor

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.

Tom Johnson recently wrote a really though-provoking post about the scope of help content. What you’re reading here is based on a comment I added to Tom’s post.

Tom describes helping out with user support for an application. He also works on the online help for this application. He describes how useful this contact with users can be. He writes:

I know that this support role, while annoying at times, is also advantageous because it gives me an insight into the real problems users are having. Through this close connection and user-informed perspective, my help can provide real answers that users want.

Talking to users. Wow! That's how it should work. My own experience, documenting enterprise-level software, is that the tech writers and the end users often never come into contact. Our end users (yes, I know, horrible expression, but what I mean is not the administrative users, or the managers, or the customer’s support staff, and not the decision makers who you sold the system to originally but who will never actually use it, but the people who have to use the software day-in, day-out as part of their jobs) … hang on, let me start that sentence again. Our end users contact their internal support staff and, if they can't help, those support people log a support call with our third-party call centre and it then gets picked up by our support people who generally manage to solve the issue very quickly and without reference to anyone else. The tech writers usually never find out about these support calls unless they take the time to check the support system regularly, or they hang out with the support guys (which tends not to happen just because we're in a different part of the building). So it's not unusual for tech writers to work on a product for months, or years, and never talk to an end user. Their knowledge of the end user tends to come second hand, through the product manager or some other SME. And it just stands to reason that if you had a direct line to your end users your documentation would inevitably be much more fit for purpose, and would get better over time.

So Tom’s post got me thinking: maybe working periodically in support is something all tech writers should do.

Tom’s post also referred to an old ITauthor podcast where Graham and I discussed how much you should document. I must admit I’d completely forgotten about that one. I should probably listen to it again some time.

But what I think I probably said in that podcast, and it’s what I really believe, is that tech writers have to get away from the habit of just bashing on and documenting stuff. Time and time again I've seen tech writers succumb to the temptation to just document whatever they see in the user interface. This is always going to result in pointlessly bloated documentation. It's the scatter-gun approach: "How should I know what users will want to know about? So I'm just going to document as much as possible."

I'm convinced the result is that a lot of time is wasted documenting things that, in a well designed interface, are obvious to the user. Those things tend to be the things users do most of the time: the basic, nuts and bolts operations that were in the original design of the application. The interface makes it easy to figure out how to do those things, so users don't need help with that. It tends to be the secondary things - the stuff that got added to the application in later iterations, and which are accessed via a menu item rather than being immediately obvious - it's those things that users tend to need some help with. But generally, to make the initial help system at least adequate for release, the tech writer needs to do a lot of thinking up front, ask a lot of questions, and get a pretty good understanding of the workflow through the application, and what tasks different sorts of users are trying to complete, and a fairly clear picture of how the application will really be used in day-to-day practice, before he or she starts writing help topics.

Tom’s post and the comments after it talk about how, as a result of users asking questions, and perhaps contributing answers to user forums, a help system can continue to grow and improve. And it’s obviously a good idea: after the initial, good-enough-for-release version of the help, with the assistance of users the user assistance gets better and better over time. In practice I think this is still all too often an aspiration rather than a reality.

Tom, who I’m assuming works on hosted WebHelp, describes how whenever he gets a support question that is now answered in the help, he goes and writes a topic answering the question, rebuilds the help and then replies to the user with a reference to the new topic. I think this is a great idea, but it only works where you host the WebHelp. If your customers host the help on their own server, or if the online help is traditional client-side CHM files, then it can be months before users see the next version of the help system.

One of the comments I really liked was by Larry Kunz. He writes:

As community-based documentation really takes off, I envision users’ requests going into forums (or something similar), and the answers being posted to the same forums - either by you or by other users. If the user community really becomes active, your role evolves into more of a curator (editing user-generated content and tagging it for findability) and less of a content producer.

Is this yet another alternative title for our role: information curator?

After commenting on the post I continued to mull it over, in particular the issue of finding information in a help system that just keeps growing and growing. Tom writes:

in a thoroughly massive help file, it becomes more difficult to find information. If a user expands a TOC to find dozens of subfolders and sub-subfolders and scores of topics within each subfolder, the system of navigation will become intimidating and cumbersome. The user will revert to keyword searches as a primary means of finding searches. After a few fruitless keyword searches without the right results, he or she may simply give up. The easy-to-use navigation system suffocates under the load of help topics

This gave me a radical thought. Isn’t it about time to do away with the TOC and the index in online help systems? Both the table of contents and the index features of printed books that were pulled across into online help, way before Google appeared in our lives, and maybe they’re just not appropriate for online help.

Surely what we need is really good search results. How do 99.9999…% of people find information online? Through a search engine. The more I think about it the more convinced I am that, if your online help had a great search engine, you wouldn’t need to worry about the system growing and growing as questions and feedback from users helped you add the information they wanted to find. Better still would be the situation where a user community forum helped you build into the help the answers to questions people had actually asked, rather than the tech writer’s best guess of what they might ask.

So come on help tool vendors, give us really good search results. The search functionality in Madcap Flare’s WebHelp leaves a lot to be desired - try doing quoted searches. If you publish WebHelp that’s publicly visible, you can use Google as your search engine and, while far from perfect, that’s probably going to give you the best available search results right now. But what if your WebHelp is hosted on an isolated corporate network? Or what if you’re tied to delivering old-style CHM help for the foreseeable future? Back to the help tool vendors in that case. Come on: give us really good search results.

From making a habit of talking to non-technical people about how they figure out how to use software, I’m convinced the majority of people wouldn’t bat an eyelid if the TOC and index disappeared from help system and the landing page for help was just a simple, Google-like page with a box to type in your question and a big old Search button.

Podcast: Play in new window | Download

Test Manager Richard Paterson joins Graham Campbell and me over lunchtime sandwiches in a rather noisy office to talk about software testing.

Technical writers in a software development department often feel like third-class citizens, with programmers as the top-dogs and testers being granted second-class status. This engenders a certain camaraderie between fellow poor relations, testers and tech writers, filling, as they do, roles that are sometimes viewed as subordinate or auxiliary to the majority party within the development department. The work of testers and tech writers often starts at around the same time, and both roles can be subject to "ship early" pressure to keep the time available to them to a minimum.

But like tech writers, testers - rightly - believe that what they do is a crucial, if undervalued, function for the creation of quality software products.

Amongst other things, I ask Richard:

• What is software testing?
• Why do we need testers? (Can't programmers just test their own code?)
• What's the difference between: unit tests, integration tests, regression tests, functional tests, user acceptance tests, lean testing ...?
• How do testers and programmers get on? (Don't programmers get really irritated by testers finding bugs in software the programmer thought was working fine?)
• Why can't we introduce automated testing and save on all the money we're paying all those testers?
• Are technical writers as useful to testers as testers are to technical writers?
• Who'd be a tester?
  

Got any thoughts on the matter? Leave a comment below.

For something completely different, have a read of Richard's blog:
ROCKETBOOTKID AND BOOSTERBOY'S PALACE OF RIGHTEOUS JUSTICE.

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

I bought my first computer in 1989. I was studying for a Publishing degree and we used the little, all-in-one, Apple Macs, with tiny black and white screens, for writing essays and doing page layouts in Aldus PageMaker (not easy on a tiny, tinsy little screen). At the end of first year, we were encouraged to get our own computers so that we could work at home and give the next year's first years a chance to get on the Macs in the computer suite.

Naturally, I wanted a Mac. But I couldn't afford one.*  So instead I settled for an Amstrad PCW 9512, which couldn't do page layout but, as an alternative to a typewriter, saved me a lot of Tippex by allowing me to edit my essays on screen before printing them out to the daisy-wheel printer that came as part of the package. I had a small collection of typewriters that immediately became obsolete (although, all these years later, I still have them - but probably not for much longer).

A couple of months back I had a clear out and I took the PCW - which had been sitting, unused in a big cardboard box in a cupboard for the past twelve years since we moved house - and I added it to a pile of slightly less ancient computer equipment at our local recycling centre (otherwise known as "the dump").

This weekend I had another chucking out session and I came across the PCW keyboard, a collection of the sturdily built 3" disks that the PCW used and some books, including a well-thumbed copy of the original user manual. I'd forgotten what a good piece of documentation that was. Buy almost any hardware or software now and you'll get a flimsy little pamphlet, with health and safety warnings and some basic startup instructions, printed in 23 different languages. The PCW 9512 came with a really substantial book.

The PCW 9512 was sold as a "Personal Computer Wordprocessor". Its main market was small businesses that couldn't afford an IBM PC. It came with LocoScript, word-processing software, and a mail-merge program for producing personalised copies of standard letters.

But in the back of the user manual there were sections on using Mallard Basic and Logo. I immediately got deeply fascinated by BASIC and I started buying the PCW Plus magazine every month for the program listings they published. I ended up spending hours and hours, usually late at night, writing a Pacman-type game, instead of studying (or sleeping). Eventually this game got too big and unwieldy for BASIC - and the more functionality I added to it, the slower it became - so I started rewriting it in C. At this point it was becoming a bit of an obsession, with long, compulsive coding sessions, but the arrival of my daughter snapped me out of the habit and it was then several years before I did any more coding.

However, the starting point for my real interest in software - I mean writing it, rather than writing about it - came with this manual for the PCW.  So, I'm a little loathe to consign it to the dump, but it's just part of the general clutter I'm trying to get rid of, so it's got to go.

For more details about the Amstrad PCW, have a look at it's page on Wikipedia:
http://en.wikipedia.org/wiki/Amstrad_PCW

* I haven't been able to find the price for an Apple Mac SE in 1989 but, from memory, I think it was almost £2000, whereas the PCW9512 retailed for £499 + VAT and came with a bundled printer.

I've just been for a run: round the loch, up the hill and through the woods at Bonally, with Lottie (my dog). I was listening to Emma Thompson on Desert Island Discs. I love it when someone you've really liked for years confirms your good opinion of them. I loved her choice of music, her choice of things to take with her to the island, and so much of what she said.

Among the things that struck a chord with me was this:

"I think it was John Ruskin said, he was talking about Capitalism and he said, 'The acquisition of each new thing just engenders a new form of weariness.' And I thought, it's the most brilliant way of describing stuff: the stuff that we accrete during our lifetimes. Greg and I certainly have got to the point where we say, 'Could we get rid of this? Yes, come on let's chuck it.' It's like you're going along in your boat and you just want to make it lighter, so you can travel faster and you can go with the wind a wee bit more."

For some unfathomable reason, the podcast I was listening to is no longer available at the BBC website, so here's a link to my own copy (until the BBC tell me to take it down):

http://www.itauthor.com/wp-content/uploads/2010/04/DID-Emma-Thompson.mp3
© BBC, 2010

And - although she knows it anyway - Patricia, it's you I really love.