User Documentation

User documentation  Is needed to help people (the users) understand how to use a computer system or software application, such as a spreadsheet.

User documentation can be:  Electronic (or “on-line”):  On-screen help menus  support  Telephone hot line  Internet support

User documentation can be:  Paper or “print” based:  Quick reference cards  Comprehensive user manuals  Reference guides  Brochures

Methodologies for producing documentation  What’s methodology?  A methodology describes the approach and the steps used to do things in a particular field.  Technical writers – the people who write user documentation – have methodologies for writing documentation

Standard documentation process  A widely accepted methodology for developing computer system documentation is the standard documentation process The standard documentation process has a number of steps

The standard documentation process

 Using the standard documentation process enables you to develop user documentation in a methodical manner The standard documentation process cont’

1. Planning: Investigate  Firstly, investigate the problem – what exactly is it that you need?  Eg.  What is the purpose of the document?  Who are your audience?  How detailed must it be?  What exactly do you need to explain?

1. Planning: Define the target audience  Who is the documentation for?  Novice users?  Intermediate users?  Experts?  Casual users?  “Parrot” users?  Transfers – eg from an older version

1. Planning: Designing the documentation  This means structuring and presenting the documentation in a way that is:  easy to use  easy to navigate through  is appropriate for your users

1. Planning Designing the documentation cont’  The design should specify:  Standards and styles for text and graphics including typographic standards (eg Font sizes and types)  Topics  Style and tone For example, it is recommended that you use: A serif font such as Times New Roman for extended text Use 10 or 12 point font size Left justify Use sans serif font for headings and within tables or diagrams Use plenty of “white space”

2. Drafting  Drafting is the actual writing of the documentation and is the most time-consuming task.  The most important thing to remember in drafting is to make the documentation easily understandable for the user.

2. Drafting: writing style The style of writing used is very important:  Use a conversational style – put things simply and clearly.  Use simple words – for example, use ‘carry out’ rather than ‘implement’, or ‘find out’ rather than ‘locate’

2. Drafting writing style cont’  Keep paragraphs and sentences short  Make sure your spelling and grammar are perfect!  Be consistent – for example, don’t call a button a button on one page, and then call it an icon on another page Use your spelling and grammar checkers!

2. Drafting writing style cont’  Use bolding, italics and capital letters consistently.  Don’t underline!  Use bullets and numbers where appropriate. Don’t use fancy, hard-to- read fonts Use heading and sub- heading styles consistently

3. Reviewing  Once a draft of the documentation has been done, it should be reviewed (checked) by another person  The reviewer should check areas such as:  Does the document do what it set out to do?  Have any areas been left out?  Is the spelling and grammar correct?  Are the instructions clear and easy to read?

3. Reviewing cont’  The drafting, reviewing, re- drafting, reviewing, process may continue through two or more redrafts. Is the draft correct, complete and clear? Draft documentationReview documentation Yes No

4. Testing  When the drafting and reviewing phases are complete, the documentation should be tested by potential users of the documentation.  If errors or omissions are found, the documentation will be redrafted and reviewed again.

5. Production  If the documentation is for use in a small organisation, production may just involve photocopying the finished documentation  For larger organisations or complex documentation, professional printing and binding may be necessary  In the case of electronic documentation, CDs may need to be burnt, or files uploaded to the internet

6. Distribution  Distribution simply involves making the documentation available to the people using the application or system it was designed for.

7. Updating  When a computer system or application is changed, the user documentation that accompanies it must also be updated.

Summary  User documentation can be electronic or paper-based  The process of developing documentation should follow a process that includes planning, drafting and reviewing  When writing user documentation, certain conventions with regard to style and typographic standards should be adhered to.  User documentation:  Should be easy to read and understand  Use short sentences and bullet points where appropriate  Use graphics where possible (“a picture paints a thousand words”)  Use appropriate fonts  Include page numbers, indexes / summaries where appropriate