Writing User Guide

If you have a flair for writing

Techwriter Sri Ram

Guidelines for writing User documentation

Contents
1. Introduction.......................................................................................4 2. Understanding the requirements of the product/client...................................4 3. Designing the document.........................................................................5
3.1. Table of contents (TOC).........................................................................5 3.2. Style Pattern......................................................................................5
3.2.1. What does a style sheet include?...............................................................5

3.3. Template...........................................................................................6

4. Writing / developing the content..............................................................6

4.1. Writing Style.......................................................................................8

5. Reviewing the content.........................................................................10

5.1. Self Review.......................................................................................10 5.2. Peer Review......................................................................................11 5.3. Peer review feedback implementation.....................................................12 5.4. Technical review................................................................................12 5.5. Final Review ....................................................................................12

6. Final Submission................................................................................13
6.1. Handling Change Requests ...................................................................13

1. Introduction
User documentation needs certain standard procedures to be followed so that user can easily understand between the lines. This helps maintain consistency across the document that you have created and those created across the organization. These guidelines can be followed while writing the end-user documents like, user guides, online help, reference guides and so on. Generally, 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. 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, as what you write completely is a depiction of what you understand from the requirements. 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, if in doubt, about the requirements.

Do not write just anything. Always clarify and proceed, since a wrongly understood requirement can result in the loss of precious time and investment. Get the document reviewed (Peer and SMEs) at stipulated timelines to avoid misinterpretations and miscommunication. Never nurture a doubt or presume things Always clarify before

proceeding.

3. Designing the document

The first and the foremost step in user guide documentation is to design the structure of your document.

3.1.

Table of contents (TOC)

Outline the TOC of the document first. Expert document writer can easily comment whether a document is neatly structured just by glancing over the TOC. The TOC must contain all the chapter headings that go into the document. For example: Introduction, Getting Started, Overview of the Features and so on. Get the TOC approved by the stake holders of the document the client, the Project lead.

3.2.

Style Pattern

Style is one of the important aspects that you have to decide at the very outset of developing a document. Styles are the instructions defined for the layout of a document in order to maintain consistency throughout the document.

Information controlled through manually applied and ad-hoc styles

a lot of re-work.

do lead to

Determine what style patterns the document will have. Most of the times such as style sheets are provided by the clients. In the absence of it, create your own style pattern (Template) for the document. Get it approved.

3.2.1. What does a style sheet include?

A style sheet typically includes: Font face, type, size Margins Heading styles, levels of heading to be used Document heading, H1, H2, H3 etc. Paragraph style Paragraph spacing, line spacing, etc.

Bullet style normal bullet style, numbered bullet style, nested bullet style.

Bullet indentation Indented text for lists Usage of emphasis bold, italics and note points Table style table row and column style, header row style, table title etc. Header and Footer style Page numbering

and more, based on the project requirements.

3.3.

Template

A template is a tool for enforcing a standard layout and look and feel across multiple pages of a document. It is a framework which allows you to work with the styles defined with in it. Without a template, 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. The document can become unstable if no template is used. Always start a project with a template. If you dont have one, ask the client if he/she is willing to provide one, if not create a template with all the styles you are required to use in the doc. Get it approved.

4. Writing / developing the content

Once your document structure is defined and the template is developed, the skeletal structure of your document is ready.

This is subject to change at any time, based on the client requirements.

You can now start adding the content to the framework. Start with the Document Information This is mostly the second page of your user guide. This is the representation of o Your documentation references

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. This includes details of version and history of revisions made to the document.

Introduction this part of the document usually talks about the overview of the document, purpose, scope and intended audience. You may also mention the document conventions, acronyms and abbreviations, and related documents in this chapter.

Next, write the Getting started section. Here, you can write about the logging in/out procedures, installation procedures and so on.

Then, write introduction of the product, description of the modules screen structure, interface design, menu bars, tool bars (if required.) This section will have a list of features with hyperlinks to the subsequent section.

Next, write the functionalities of the product. All the How to procedures will come under this section. Give a step-by-step description of the procedures. Provide screen captures wherever required.

As you proceed with How Tos, it is always recommended to break down the information to sub-levels for more comprehension of the end-user. Once all the functionalities of the software application/product are given, next, create an Appendix. An Appendix section consists of supplementary material that is collected and appended at the end of a document. It contains information that is important to but is not the main idea of the document. For example, a table that carries important information, but is not relevant to the steps you are writing, can find a place in the Appendix. Appendix is not mandatory to every document. It is optional.

Next, develop a Glossary. A Glossary is a list of terms that appear in the document. The terms are defined and explained briefly in the glossary. The Glossary usually appears in the alphabetical order. Glossary is not mandatory to every document. It is optional.

Next create an Index. An Index is an alphabetical listing of names and topics along with page numbers where they are discussed.

A user guide / help is said to be complete only when it consists of all the above components.

4.1.
Heading

Writing Style

Create the heading styles to suit the client requirements. That is, provide the font size, type and color as required by the client. Do not use colon after a heading. Paragraph To design a style for paragraph, provide before and after space to the paragraph. Provide 1.5 line space to the text within the paragraph. Do not have a paragraph running into more than 4 to 5 lines. Do not give extra spaces after each paragraph. Note Any thing that provides additional information to the description/steps within the text, provide it as a Note. Always write the notes in a new line. Do not highlight the note, as it is not providing the most important information but only some additional information. (Base your note style on the client requirements.) You can also use icons/graphical images to represent notes. Bullets and Numbering and Nested bullets Bullets are used in item lists and descriptions. Do not use ordinary bullets in writing the procedures. Numbered lists are used to write step-by-step procedures. Use 1., 2.,3. style numbering.

Nested bullet list - Use the solid bullets at the highest level. At the next level, use the empty circles and use dashes at the third level. Nesting the bullets beyond three levels is not advisable. Nested number lists: use the 1., 2.,3. style at the highest level, a.,b.,c.,at the next level and i.,ii.,iii at the third level.

Tables

Preference should be given only to the styles provided by the client, if any.

Follow one table style throughout the document. Do not leave empty spaces in the table, remove all empty spaces in rows as well as columns. Provide a table tile if required by the client. Links All hyperlinks should be checked if they are linking to the right document/web page/figure. Use of Italics Italics are generally used for emphasis. They are generally used for emphasizing the names of related documents, or any other references. Do not use italics in heading styles. Use of underline Usage of underline for emphasis has become obsolete and should not be used in headings. Figures/Images Figures should be used judiciously in the documents. Do not copy paste the figures liberally in the document. Cut only the required portions of the figure, for example, dialog boxes, icons etc. Do not paste entire window as it will only add to cluttering. Provide a figure title, for example, Figure 1: xyz Central align the images and provide a thin border around the images so that the image components do not appear disconnected. If the image is big and complicated, provide a neat labeling. However, its best to base your table design on the customer requirements

How to use dialog box/form elements in writing The following writing patterns are used while writing about the dialog box/form elements. However, always make sure how the client wants them written. Buttons: If the name of the button is Set Up, write Click Set up. Note that the name of the button is made bold. Do not write Click on the Set up button. It is a sheer wastage of words. Similarly, write, Click Yes. Text box: Write, Enter your password in the text box or Enter the value in the text box. Drop-down list: Write, select 2001 from the drop-down list. Radio button/ Check boxes: Write, Select the XML radio button. deselect the check box, write, Uncheck/disable the xyz check box. To

5. Reviewing the content

Reviewing is another very important aspect of document development life cycle. A review is a necessary process at every milestone of the document lifecycle. A well reviewed document reduces the number of iterations from the customer and thus improves the turn around time. There are four review stages that should be carried out before sending the document to the client. They are: Self review Peer review Technical review Final review (Client Review)

5.1.

Self Review

Self review is done by the writer who is responsible for the document. You do a self review for correctness of language, formatting and flow of contents. At this stage, you also test the document against the functionality of the application. Check if the document matches the work flow of the application. Self Review checklist: A complete self review of the document is mandatory before you send it for a peer review.

Spell check This is the most important review activity you should do before you send the document to the next stage of the review. Run your document through a spell check to make sure there are no spelling errors. If this is not done, 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, for example, provide a space after a full stop, comma, question mark, colon and so on. Formatting Check if the template is applied and the styles are uniform throughout the document. Images Check if the images are aligned properly. Provide a thin border to the images so that the image components do not appear disconnected. Provide neat labeling to the images, if the image is big and complicated. Once the self review is complete, send the document to the assigned peer reviewer, with a CC to the Project lead.

5.2.

Peer Review

Peer review is generally done by another writer in the team who is also involved in the project. The peer reviewer may also follow the Self review checklist while reviewing the document. Make sure all the points in the check list are carried out before sending it out for a technical review by the client/developers.

How to provide review comments? Insert comments in the document wherever required. Use Insert Comments and not the Track changes to provide your comments. Once the peer review is complete, send the document back to the writer with a CC to the Project lead.

5.3.

Peer review feedback implementation

Implementing peer review comments is as important as reviewing itself. If the review comments are not implemented, the purpose of the reviewing itself is lost. Accept the comments where you think the modification is required and reject them where the change is not really required. Make sure, every comment made by your peer writer is addressed.

5.4.

Technical review

Send the document for a technical review at this stage. The Project lead (or as arranged) will send the document to the developer(s) for a review. 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. Implement the comments received from the technical review. Write/speak to the developer(s) if any clarification is required. By now the document might have changed quite a bit. Check it once more and send it out for a final review to you Project lead. The document should be sent for a final delivery only after a final check is done by the PL. (If anything goes wrong, the blame is on the PM!! How do you like it)

5.5.

Final Review

The final review is done by the Project Lead. This round of review checks all the points mentioned in the self review, makes sure all the peer review and technical review comments are implemented. This review also ascertains that the customer requirements are fulfilled and the finished product (document) is presented efficiently and professionally.

6. Final Submission
Make sure the format the client wants the document to be delivered. Generally, they require both the source files and the PDF. Sometimes, the client may also require the information to be presented in different other formats such as web help, CHM, etc. The Project lead sends off the final copy of the document to the client.

6.1.

Handling Change Requests

Change is a necessary milestone in product development life cycle. Change in the structure of the product can come in at any stage of the development, even after the document is finally delivered. So, plan for any such emergency and get ready to work on the changes. However, extra time will have to be assigned for the change management.