Home >> News and Information >>Copy of Planning user documentation - a guide for software project managers
Planning user documentation - a guide for software project managers - Part 3
By Carol Johnston, Technical Director.
If you would like a PDF version of this article, contact us via the form below:
Spreading the authoring work more evenly
The traditional close-to-launch timing of the documentation presents, as mentioned already, a project risk. To reduce the amount of time and resource required at this busy time, there are a number of tasks that your technical author can do earlier on in the project to reduce the project risk.
Look and feel of the Help system
These days, authoring tools for technical writers are making it possible to create Help systems with a customised look-and-feel. Software houses are now getting more interested in their Help systems looking better than the rather grey-looking standard Help viewers (for example WinHelp and HTML Help) and more in line with the software itself. Creating a customised look-and-feel takes time. But this is one of tasks your technical author can be doing in the design stage, as soon as the software look-and-feel is agreed.
Structuring the Help system
Depending on the complexity of the software, it may be possible for the technical author to sketch out a rough structure for the topics in the Help system after the design stage. This would be a flexible work-in-progress structure, but would at least set out a draft of the types of information to be documented.
Conceptual topics
Generally speaking, the majority of Help topics in a Help system are procedural. They tell the user how to do something by giving detailed step-by-step instructions on using the interface so, in the main, are best left until the software is more or less stable. However, there will also be some information for the user that is of a conceptual nature. It may be possible for your author to document some such concepts during and after the design stage.
Summary of where your documentation fits into your project plan
Getting more value from your technical author
Specifications and design stage
It may not be something you have considered, but since good technical authors have expertise in designing information, they can also provide useful input at the specifications and design stage. Getting your technical author on board at this stage can help make the user interface more usable. This reduces your technical support costs and may reduce the time it takes to document the software. It may be something as simple as labelling or ordering the fields on the dialogs in a more helpful way. Moreover, authors with experience in writing for screens will know what sorts of layouts will and won't work. They can provide valuable input for decisions on the structuring and the look-and-feel of the interface. And remember that they are very much user-focussed – providing balance to what may be an over-enthusiastic graphics design team! You can think of the technical author as the representative of your average user as the specifications are decided and the design progresses.
Embedded Help
If your technical author is contributing expertise during the specification and design stage of the project, it may well be that the traditional paper manual/online Help 'documentation', created at the very end, is reduced in scope or even unnecessary. In other words the 'necessary nuisance that takes up valuable manpower to create and review just when deadlines are looming' is all but eliminated. The user interface can contain its own 'user assistance'. This kind of approach is known as Embedded Help. Exactly how and where the assistance is provided is part of the specification and design process. For example, one successful technique is to have a dedicated (but shrinkable) part of the interface for displaying context-sensitive assistance.
Build stage
If present at all relevant meetings, the number of questions your technical author will have for the programmers when writing the Help content will be reduced, saving precious time near the end of the project.
Testing stage
If you are planning to perform usability testing, your technical author can participate in designing and giving the tests and in interpreting the results.
Post rollout
If you are outsourcing, the external organisation may provide a service for logging and collating user feedback, reporting it to you and updating the Help where appropriate.
Summary
Providing online assistance for software is important since it can reduce costs of technical support and make life easier for your users. However, documenting software is not a trivial task. It requires time and resources for writing and reviewing that must be included in the overall project plan.
The documentation work is traditionally implemented after the software is reasonably stable – during the testing stage. However, getting your author on board earlier spreads the work more evenly, reducing project risk. Moreover, including your author in design decisions and usability testing can improve the user interface.
Comments received on this article
We heard this (paraphrased) comment from one of our clients:
"The legal contracts with our clients include a "User Acceptance Testing" (UAT) clause which entitles the client to claim a 25% discount if the software fails UAT. Sometimes our company allocates insufficient time to update the documentation in readiness for the software release date. So the software can be shipped with documentation that does not accurately describe what the system does.
This means we can fail UAT because the software doesn't do what it says it should do in the documentation. We could lose 25% of what we invoiced."
Subscribe to our Newsletter and don't get left behind
The Cherryleaf newsletter is the world's most popular monthly newsletter on technical communication. It will help you to stay up-to-date on issues facing documentation professionals.
To subscribe to this free newsletter, enter your name and email address in the form below.
"Cherryleaf is one of the best technical authoring houses in the business, and Ellis [the sales director] is profoundly knowledgeable, professional and approachable. Highly recommended for anyone requiring top-notch documentation or training services."
Julian Maynard-Smith, technical author and journalist
Back to Part 2
