1. Important note: in the 2011-2014 study design, both IT Applications and Software Development have user documentation as part of U4O1. Note that the ITA user doc must be onscreen, created with web or multimedia software. In SD it need not be onscreen, and you user "appropriate" software. By Mark Kelly mark@vceit.com Vceit.com VCE IT Lecture Notes Writing User Documentation For ITA U4O1 and SD U4O1

2. Important Important note: In the 2011-2014 study design, both IT Applications and Software Development have user documentation as part of U4O1. The ITA user doc must be onscreen documentation, created with web or multimedia software. In SD it need not be onscreen, and you use "appropriate" software.

3. Note Important note: your user documentation should explain how to re-use the solution, not how the solution was created. You need to explain how someone should use the solution and produce the output. Do NOT explain how to name cells or do VLOOKUP! You would explain how to add/change/delete data from the and how to print, save and exit.

4. PLANNING DOCUMENTATION Don't try to make it up as you go along - you'll end up in a mess. Jot down the main headings first. Worry about details later. Get all the top level headings sorted out first. If you have a choice, decide on your format - onscreen or printed? (ITA is onscreen; SD does not have to be)

5. Minimum Contents 1. How to open the solution. 2. How to enter new data 3. How to change data 4. How to save data 5. How to produce output 6. How to exit the solution

6. Planning example How to reuse my mail merge solution. Open the form letter. Edit the form letter Open the data file Add/delete/edit data Save files Preview the merge Carry out the mail merge Print the output Exit the programs.

7. Then Now you should make sure the main headings are in the right order. Organise subheadings under main headings.

8. 1.open the form letter 2.edit the form letter 3.open the data file 4.add/delete/edit data 1.adding data 2.deleting data 3.editing data 4.what to do if you add or delete columns/fields 5.save files file 1.naming suggestions 2.folder structure suggestions 3.how to save 6.preview the merge 1.using preview buttons 2.warning about SKIP IF not working during preview 7.carry out the mail merge 1.merging to a new document 2.merging to the printer 8.print the output 1.print options (e.g. number of copies, printing certain pages) 2.how to start printing 9.exit the programs. 1.warn about saving first 2.How to close Word and Excel

9. Numbering Use numbered headings as part of your documentation. Use autonumbering where possible. If you number paragraphs manually, deleting items will mean you will have to manually renumber all of the following points. Autonumbering will automatically update paragraph numbering as points are added or removed.

10. Numbering A common numbering format is like this 1. Main heading (level 1) – 1.1 Level 2 subheading 1 of main – 1.2 Level 2 subheading 2 of main 1.2.1 Level 3 subheading 1 of 1.2 1.2.2 Level 3 subheading 2 of 1.2 – 1.3 Back to level 2 subheading 2. Back to level 1 heading This makes it clear which topics are contained within other topics.

11. Getting started Enter the headings and subheadings. Leave the actual instructions for later. You must provide some way for the user to find topics in your document: the minimum you need is clear headings. A table of contents or index is also useful, especially with larger documents. These can be created automatically if you use heading styles.

12. Automated heading styles Office 2003 Office 2007 Dreamweaver

13. Why use heading styles? In Word, you can create automatic indexes and tables of contents. Word uses heading styles. If you add or delete headings or sections, you can regenerate your table of contents with a single click of the mouse.

14. Why use heading styles? The software will format the heading using a consistent style (font, size, bold/italic etc). Users can quickly find content by skimming through the document looking for headings by their appearance. If you decide to change heading formats, you just change the style and all headings using that style are instantly reformatted.

15. Design Elements Elements related to functionality are Structure Usability Accessibility (for those with disabilities) Navigation and load time Appropriateness Relevance.

16. Presentation Poor presentation can really hurt the effectiveness of your user documentation. Remember the design elements relating to appearance: – proportion (visual hierarchy) – orientation (direction/ aspect) – clarity and consistency – colour and contrast.

17. White Space – done badly Lots of space on your page makes your documentation easier to read.White space visually separates topics and makes skim reading far easier.Use nice wide margins to make the text width narrower. Short lines are easier to read.Put at least one blank line between different points,and between graphics and text.

18. White Space – done well Lots of space on your page makes your documentation easier to read. White space visually separates topics and makes skim reading far easier. Use nice wide margins to make the text width narrower.

19. Icons Consistent use of meaningful icons greatly helps the reader. Icons highlight certain types of information. The reader can find desired information (e.g. warnings) by scanning for icons. E.g.

20. Icons Warning Tip Heres a link

21. Screenshots Pictures convey maximum information in minimum time. Trying to describe some buttons in words can be difficult, wordy and inaccurate. It would be far better for both you and the reader to say "Click this button" and have a picture of it. It's a win-win: – you write less – the user has less to read – the message is clearer – It saves the reader time

22. Screenshots Use dedicated screenshot utilities where possible. They can include the mouse pointer in the image, autosave and autonumber shots, crop etc. Or use the PRINTSCREEN key and paste the image from the clipboard to the paint program to process it. To capture the active window, press ALT+PRINTSCREEN.

23. Then you can edit it in a graphics editor

24. Decorative Graphics Decorative graphics, such as dividers, can make the documentation more pleasant to read and can help divide it into sections. Use them in moderation. They should not be irrelevant, offensive, or distract from the purpose of the documentation.

25. Grammar, expression Dont confuse the reader. – "replace R23 with a 50 K ohm lesistor. – "Contrast knob will make picture bright but not dazzling. – "Keep off the capacity transformable or magnetic. – "Undoing a Redo will redo the original Undo."

26. Spelling Use the spell checker. Beware of words you know you confuse (e.g. "its" versus "it's"). Use simple expression and short sentences. Don't try to use impressive words to show off: you will either get them wrong and look stupid, or your reader wont understand you.

27. Colour Schemes Overlapping colours must have good contrast. Dont use red/green or other colourblind combinations. Text on photos can become unreadable Colour can be a useful tool to identify types of discussion, e.g. red for warnings.

28. Typefaces No more than 2 typefaces per page. Use them consistently, for a clear purpose – e.g. Arial for headings, Times New Roman for body text. Showing off how many fonts you have on your computer is immature and unimpressive. NEVER use decorative typefaces (e.g. gothic) for body text! Keep font sizes big enough to read

29. Printed page size and format Printed documentation is often in book format. Other formats for different purposes. – Pocket-sized format? – Wall poster? – Leaflet?

30. Jargon Jargon is specialist language used by people in an area of knowledge - e.g. pilots, doctors, skateboarders, IT workers. It is a shorthand way of expressing specialist concepts. Jargon is not bad if used with people who understand it. Know your audience: avoid or explain jargon used with non-expert readers

31. Jargon Explain in more detail if readers might be complete beginners If jargon is really needed to save time, explain the term when you first use it.

32. Use simple words instead of big ones GOODBAD UseUtilise NowAt this point in time DoAccomplish Find OutAscertain TryEndeavour HelpFacilitate PlaceLocality AboutWith regard to ByBy means of IfIn the event that Too ManyExcessive number of

33. Or avoid words altogether

34. How much detail? Can be a tricky decision. It depends on things like: – skill level of the audience – the dangers inherent in the task – the complexity of the topic Make sure you cover the entire topic and don't leave out vital bits like producing the output.

35. Testing Take your draft documentation to a typical audience member to test it. – Get the victim to carry out the instructions. – Take note of errors and confusion and fix those bits – Ask them to carry out an action described in the documentation.

36. Testing Test it yourself by playing the 'Stupid Robot Game'. – Carry out the instructions as if someone else had written them. – Do exactly what the instructions say - no more, no less. – Don't "fill in gaps" where information is missing. – Can you satisfactorily re-use the solution? – If not, fix it.

37. Warning! If there is any action that could cause grief to the user (e.g. data loss), they should be suitably warned before the danger strikes. Saying "Now click the EXIT button - oh, by the way, make sure you save first" is a dangerous piece of foolishness.

38. Finally Information in the documentation must be easy to find. Logical organisation Headings Numbered sections Electronic search facility

39. Finally Good documentation is: current (up to date) clear (easily read, easy to understand) concise (as short as possible without leaving things out) complete correct

40. Finally Use pictures where possible. Warn of possible dangers before the dangerous action is described. Test the documentation. For practice, try writing instructions on how to: – How to play Solitaire – How to crop an image in Photoshop – Using CSS in Dreamweaver

41. By Mark Kelly mark@vceit.com vceit.com These slideshows may be freely used, modified or distributed by teachers and students anywhere on the planet (but not elsewhere). They may NOT be sold. They must NOT be redistributed if you modify them. IT APPLICATIONS SLIDESHOWS