Introduction
This article describes the best practices for technical writers while developing help systems.
Apart from maintaining consistent tasks, and efficacy, there are lots of other factors that make a help system useful. The target is to grab the attention of the users who might not want to give it to you. Generally, users need help file when they can't solve queries on their own. Providing the right information on the right topic makes it easy for users to use the help system. The same way, synchronization, proof reading, and consistency are important factors for any document. Again, users need sufficient information, neither more nor less. Less information lands them in insufficient knowledge, and more information makes them bore and frustrated. Thus, in both cases, the purpose of documenting a help fails.
Here is a list of factors that are important for making any help document a success:
- Identification of audience: This step is required to identify the readers and the kind of information they are looking for. For technical readers, we can use technical jargons, short forms etc., but for non-technical readers, we have to explain the technical terminologies, conventions and methodologies, etc.
- Determine time limits: Estimate the time required to develop the help system. Estimate the target dates for a set of topics, and determine the scope of the project. These points influence the deadline of the entire project.
- Layout of help file: Online help, PDFs, Word files, etc� these are the various formats in which a help document can be developed. The layout of a help file should be clear to technical writers. The use of software to develop help files depends on how the help file is presented. Online help systems require Robohelp, Word files require MS-Word, and PDFs require Acrobat Reader for viewing.
- Write a style guide: Develop a style guide on the basis of the format selected to develop a help system. View various help systems. What is the most common point that you have come across? Simple, accurate, and concrete: these three characteristics should be part of any help system. Development of a style guide depends on the output of the help system. The style guide for an online help system will be different from the one developed for PDFs. Style guides should encourage the use of active voice, omit needless words, have a grammar style, use positive sentences and a task oriented approach, should not have overlapped headings, use short and simple sentences, and use second person. A style guide can be considered as a set of instructions to be followed while documenting a help system.
One of the recommendations is to develop templates for user manuals, installation guides, administration guides, etc.
- Develop the content: This is the most challenging job. Parameters such as complete paragraphs, positive statements, use of active voice, spelling conventions, etc. should be kept in mind while documenting help. The information entered in a help file should be complete and consistent. The main points should be written as notes, or highlighted. Development of content is directly related to the type of audience. The content (language) of a help file should be capable of explaining concepts to the readers. Irrespective of the audience, a help file should consist of short and simple sentences.
- Review help: This is the most important step in a project. Ensuring that the help system is effectively built is most important for a technical writer. You can create a checklist to ensure that the objectives of developing a help system are successfully met.
- Test help: Another major step is to test the help system. This includes testing the correct deployment, context sensitivity (if included), content etc. Here also, a checklist can be maintained to ensure the accuracy of the help system.
- Freeze and version control: Freeze the help file and upload it in a version control system introduced in your company. The most popular version control systems are VSS and CVS. This will help technical writers and other technical members to ensure that they are using the latest help files.
