Documentation the ScreenSteps way
June 12th, 2010 1 Comment
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.
Potentially similar posts
- The four levels of software support – June 2010
- Does online help need an overall structure? – June 2010
- 5 Steps to Improving Your Software Documentation – June 2010
- PDF Manuals: The Wrong Paradigm for an Online Experience – June 2009
- The help system or CSH topics – which is more important? – October 2008
Test Manager Richard Paterson joins Graham Campbell and me over lunchtime sandwiches in a rather noisy office to talk about software testing.
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
June 13th, 2010 at 3:02 pm (#)
And ScreenSteps natively supports publishing to MindTouch where post editing and linking to others tutorials and troubleshooting guides are possible. We've been using it for a while for our own docs. It's a really nice product!