2. Agenda Writing a manual Our audience Our voice Conventions 3. Writing a Manual: Challenges
Style decisions
4. Voice rules Understanding the audience
Pracitcal Limitations
5. Writing Challenges: Other Sources
6. Many other sources
7. GNOME documentation 8. Community and user documentation and guides Problems
9. Licensing is incompatible 10. Technical level is too high 11. Our Audience: New Users
12. May be new computer users 13. Assume basic keyboard and mouse skills, concept of a modern GUI with overlapping windows 14. Do not know other terms
15. ethernetvs.wifi 16. IMAPvs.POP 17. sudovs.root 18. Our Audience: New Users
19. Define or explain everything more difficult than clicking the mouse button 20. Be very precise in your language to make sure the user knows what you are describing
Start with the simple, end with the advanced 21. Our Audience: Eager To Learn
22. Task oriented, wants to know how to:
23. Scan a document 24. Edit spreadsheets 25. Keep the system up to date May read the manual in large chunks, not purely as a reference work but as a book 26. Our Audience: Eager to Learn
27. Think in terms of user tasks, not technology
Use asides and margins to inform users about advanced topics, or how to learn more 28. Do not patronize 29. Our Audience: International
Even for the English version, need to assume an international audience
Idioms, humor, complex vocabulary will cause problems 30. Our Audience: International
31. Always use a simpler synonym 32. Repeat yourself
Use short paragraphs with a few sentences in each one 33. All English-language documentation for Ubuntu uses American spelling 34. Our Voice: Confident
35. In writing, we need to be confident of our opinions
36. Correct: 'Ubuntu is a secure operating system' But we shouldn't claim to be prescient
37. Better: 'Ubuntu should open a window' 38. Our Voice: Direct and Calm
39. Correct: If you have a Gmail account, you can... Avoid superlatives and marketing speak
40. The easiest way... 41. Ubuntu is excellent at... 42. Our Voice: Slightly Opinionated
43. But we should only recommend one or two
44. Don't mention other options unless they are actuallybetter , not just because they exist 45. OK to have both mouse & keyboard directions Try to steer users away from bad decisions, but do not preach
46. Our Voice: Aligned with Users
Guide them from justifying the need to completing the task
47. Conventions: Attribution
Attribute desktop actions to Ubuntu, application actions to the application
48. Empathy will open a window... Ensure active voice
49. Bad: A window will be opened by Empathy 50. Conventions: Standard GUI Terms
51. Click onother buttons check box
52. Choose , orselect / deselect 53. A check box is eitherselectedorunselected 54. Can also write option instead of check box 55. Conventions: Standard GUI Terms
56. The name of the dialog is its title drop-down list
57. Usethename drop-down list tospecify drop-down combination list
58. Not combo box 59. Conventions: Standard GUI Terms
60. double-click on something drag
61. dragsomething to some place 62. Conventions: Standard GUI Terms
list box
Main Menu
menubar
63. Choosefrom a menubar 64. Conventions: Standard GUI Terms
Login, shutdown
popup menu
radio button
65. Chooseorselect 66. Conventions: Standard GUI Terms
tab
text box
Top Related