Writing User Guide

If you have a flair for writing…

Techwriter Sri Ram

Guidelines for writing User documentation .

.4..................................13 6.........2..10 5................................................... Reviewing the content..... Style Pattern............................................ Self Review........6 4..........5 3...................................... Table of contents (TOC).............. Template.............. Introduction............... Writing / developing the content....................................5 3.............................. Handling Change Requests ....... Writing Style.. Peer review feedback implementation....................................1............................................. Technical review..........................................5 3............................................1.............................................. What does a style sheet include?...........................................................................8 5.......2...........................6 4...........2...................1......................................11 5............................1.....................................3.........................................10 5........................5 3..1.12 5. Understanding the requirements of the product/client........................................4 2........................................3.Contents 1................13 ................................4 3....... Final Submission...5............................................................................................................................................................12 6................................................... Final Review .......................... Peer Review............................................... Designing the document...................12 5...............

1. Get the document reviewed (Peer and SMEs) at stipulated timelines to avoid misinterpretations and miscommunication. technical writing process is broadly divided into 5 stages: • • • • • Understanding the requirements of the product/client Designing the document Writing/developing the content Reviewing the content Handing over the final product/document 2. Never nurture a doubt or presume things – Always clarify before . Understanding the requirements of the product/client A thorough understanding of the requirements laid down by the client is a must before you embark on writing any user documentation. This is important. user guides. as what you write completely is a depiction of what you understand from the requirements. reference guides and so on. Introduction User documentation needs certain standard procedures to be followed so that user can easily understand between the lines.     Do not write just anything. This helps maintain consistency across the document that you have created and those created across the organization. if in doubt. Who can help you in understanding the scope and requirements? • • • Business analyst Developers of the application Your Project leader You must always touch base with these personnel. since a wrongly understood requirement can result in the loss of precious time and investment. Generally. These guidelines can be followed while writing the end-user documents like. about the requirements. Always clarify and proceed. online help.

Table of contents (TOC) Outline the TOC of the document first. The TOC must contain all the chapter headings that go into the document. H2. Get the TOC approved by the stake holders of the document – the client. create your own style pattern (Template) for the document.1. • Paragraph style – Paragraph spacing. do lead to Determine what style patterns the document will have. In the absence of it. .proceeding. 3.2. etc. What does a style sheet include? A style sheet typically includes: • • • Font face. Style Pattern Style is one of the important aspects that you have to decide at the very outset of developing a document. Designing the document The first and the foremost step in user guide documentation is to design the structure of your document. Overview of the Features and so on. Most of the times such as style sheets are provided by the clients. Getting Started. 3. Expert document writer can easily comment whether a document is neatly structured just by glancing over the TOC. For example: Introduction. 3. H3 etc.  Information controlled through manually applied and ad-hoc styles a lot of re-work. Styles are the instructions defined for the layout of a document in order to maintain consistency throughout the document. line spacing.1. H1. the Project lead. 3. size Margins Heading styles.2. type. levels of heading to be used – Document heading. Get it approved.

you could still have entered all of the required content but it would have been far more difficult for you to do the formatting and maintain consistency across the document. nested bullet style. based on the client requirements. Always start a project with a template. Writing / developing the content Once your document structure is defined and the template is developed. • Start with the Document Information – This is mostly the second page of your user guide. Get it approved. 3. table title etc. numbered bullet style. Template A template is a tool for enforcing a standard layout and look and feel across multiple pages of a document. 4. This is the representation of o Your documentation references .  This is subject to change at any time. It is a framework which allows you to work with the styles defined with in it. header row style. If you don’t have one. The document can become unstable if no template is used. if not create a template with all the styles you are required to use in the doc. • • • • • • Bullet indentation Indented text for lists Usage of emphasis – bold. Without a template. You can now start adding the content to the framework.3. ask the client if he/she is willing to provide one. Header and Footer style Page numbering … and more. based on the project requirements. italics and note points Table style – table row and column style.• Bullet style – normal bullet style. the skeletal structure of your document is ready.

Here. For example. Give a step-by-step description of the procedures. An Appendix section consists of supplementary material that is collected and appended at the end of a document. next. tool bars (if required. You may also mention the document conventions. • Introduction – this part of the document usually talks about the overview of the document. write introduction of the product. Provide screen captures wherever required. installation procedures and so on. scope and intended audience. Once all the functionalities of the software application/product are given. . but is not relevant to the steps you are writing. write the Getting started section.o o o o o • Initiation date of the document Authors and role description Reviewer and role description Approver and role description Relevant dates Document Amendment information – This follows immediately after the Document information section. It is optional. a table that carries important information.) This section will have a list of features with hyperlinks to the subsequent section. description of the modules – screen structure. can find a place in the Appendix. purpose. menu bars. and related documents in this chapter. • Then. create an Appendix. • Next. It contains information that is important to but is not the main idea of the document. you can write about the logging in/out procedures. All the ‘How to’ procedures will come under this section. Appendix is not mandatory to every document. interface design. it is always recommended to break down the information to sub-levels for more comprehension of the end-user. This includes details of version and history of revisions made to the document. write the functionalities of the product. • Next. acronyms and abbreviations.  • As you proceed with How To’s.

as it is not providing the most important information but only some additional information. A user guide / help is said to be complete only when it consists of all the above components. Do not use ordinary bullets in writing the procedures. Do not use colon after a heading. Paragraph To design a style for paragraph. • Numbered lists are used to write step-by-step procedures. Do not highlight the note. Do not give extra spaces after each paragraph. That is. provide ‘before’ and ’after’ space to the paragraph. Provide 1.3. (Base your note style on the client requirements. Always write the notes in a new line. Glossary is not mandatory to every document.) You can also use icons/graphical images to represent notes.1. type and color as required by the client. The terms are defined and explained briefly in the glossary. The Glossary usually appears in the alphabetical order.. 2. Heading Writing Style Create the heading styles to suit the client requirements. Use ‘1. A Glossary is a list of terms that appear in the document. • Next create an Index..5 line space to the text within the paragraph. 4. . provide it as a Note.• Next. Note Any thing that provides additional information to the description/steps within the text. Do not have a paragraph running into more than 4 to 5 lines. An Index is an alphabetical listing of names and topics along with page numbers where they are discussed. Bullets and Numbering and Nested bullets • Bullets are used in item lists and descriptions. provide the font size. develop a Glossary. It is optional. …’style numbering.

Figures/Images Figures should be used judiciously in the documents.. They are generally used for emphasizing the names of related documents.• Nested bullet list . icons etc.iii at the third level. …’style at the highest level.Use the solid bullets at the highest level.3. for example. If the image is big and complicated. ‘a. for example. Cut only the required portions of the figure. Use of Italics Italics are generally used for emphasis. use the empty circles and use dashes at the third level. provide a neat labeling. Do not use italics in heading styles. if any..at the next level and i. Use of underline Usage of underline for emphasis has become obsolete and should not be used in headings.. Do not copy paste the figures liberally in the document.. dialog boxes. Provide a table tile if required by the client. Nested number lists: use the ‘1. Figure 1: xyz Central align the images and provide a thin border around the images so that the image components do not appear disconnected..b. or any other references. Follow one table style throughout the document. Provide a figure title. Do not leave empty spaces in the table.  Tables Preference should be given only to the styles provided by the client. At the next level. Nesting the bullets beyond three levels is not advisable. Do not paste entire window as it will only add to cluttering.ii. remove all empty spaces in rows as well as columns.. Links All hyperlinks should be checked if they are linking to the right document/web page/figure. it’s best to base your table design on the customer requirements .. However. 2.c.

They are: Self review  Peer review  Technical review  Final review (Client Review) 5. Do not write ‘Click on the Set up button. ‘Click Yes. A review is a necessary process at every milestone of the document lifecycle.’ deselect the check box.1. write.’ Drop-down list: Write.’ write ‘Click Set up. Check if the document matches the work flow of the application. At this stage. formatting and flow of contents. A well reviewed document reduces the number of iterations from the customer and thus improves the turn around time. you also test the document against the functionality of the application. You do a self review for correctness of language.’ Text box: Write. However.How to use dialog box/form elements in writing The following writing patterns are used while writing about the dialog box/form elements. write.’ To 5. Self Review Self review is done by the writer who is responsible for the document. ‘Enter your password in the text box’ or ‘Enter the value in the text box. There are four review stages that should be carried out before sending the document to the client.’ It is a sheer wastage of words. Similarly. .’ Note that the name of the button is made bold.’ Radio button/ Check boxes: Write. Reviewing the content Reviewing is another very important aspect of document development life cycle. ‘Uncheck/disable the xyz check box. ‘Select the XML radio button. ‘select 2001 from the drop-down list. always make sure how the client wants them written. Self Review – checklist: A complete self review of the document is mandatory before you send it for a peer review. Buttons: If the name of the button is ‘Set Up.

Images Check if the images are aligned properly. with a CC to the Project lead. send the document to the assigned peer reviewer. Run your document through a spell check to make sure there are no spelling errors. provide a space after a full stop. The peer reviewer may also follow the Self review checklist while reviewing the document. Provide neat labeling to the images. If this is not done. comma. it shows poorly on the proficiency of the writer. Punctuation • • • unnecessary capitalization commas at wrong places unnecessary spaces Also check if a space is provided after every punctuation mark is used. Formatting Check if the template is applied and the styles are uniform throughout the document. Once the self review is complete. colon and so on. Make sure all the points in the check list are carried out before sending it out for a technical review by the client/developers.Spell check This is the most important review activity you should do before you send the document to the next stage of the review.2. question mark. Provide a thin border to the images so that the image components do not appear disconnected. if the image is big and complicated. 5. for example. . Peer Review Peer review is generally done by another writer in the team who is also involved in the project.

send the document back to the writer with a CC to the Project lead. . 5. the blame is on the PM!! How do you like it) 5. The Project lead (or as arranged) will send the document to the developer(s) for a review.3.5. Write/speak to the developer(s) if any clarification is required. The document should be sent for a final delivery only after a final check is done by the PL. Once the peer review is complete. (If anything goes wrong. 5. By now the document might have changed quite a bit. This review also ascertains that the customer requirements are fulfilled and the finished product (document) is presented efficiently and professionally. the purpose of the reviewing itself is lost. makes sure all the peer review and technical review comments are implemented. This round of review checks all the points mentioned in the self review. Peer review feedback implementation Implementing peer review comments is as important as reviewing itself. Make sure. The technical review is done by the developers of the application/product. Functionality and workflow and correctness of descriptions/procedures are checked in technical review. Check it once more and send it out for a final review to you Project lead.4. Use Insert  Comments and not the Track changes to provide your comments.How to provide review comments? Insert comments in the document wherever required. Accept the comments where you think the modification is required and reject them where the change is not really required. If the review comments are not implemented. Final Review The final review is done by the Project Lead. every comment made by your peer writer is addressed. Implement the comments received from the technical review. Technical review Send the document for a technical review at this stage.

Change in the structure of the product can come in at any stage of the development. So.1. CHM. the client may also require the information to be presented in different other formats such as web help. However. The Project lead sends off the final copy of the document to the client. . 6. Handling Change Requests Change is a necessary milestone in product development life cycle. Sometimes. they require both the source files and the PDF. Final Submission Make sure the format the client wants the document to be delivered. extra time will have to be assigned for the change management.6. plan for any such emergency and get ready to work on the changes. Generally. etc. even after the document is finally delivered.

Sign up to vote on this title
UsefulNot useful