Writing the Ubuntu Manual


Published on

Published in: Technology
  • Be the first to comment

  • Be the first to like this

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Writing the Ubuntu Manual

  1. 1. Writing Style What to do and what not to do When writing for the Manual presented by Ilya Haykinson [email_address]
  2. 2. Agenda Writing a manual Our audience Our voice Conventions
  3. 3. Writing a Manual: Challenges <ul><li>Content decisions </li><ul><li>What to include, what to leave out </li></ul><li>Style decisions </li><ul><li>Grammar rules
  4. 4. Voice rules </li></ul><li>Understanding the audience </li><ul><li>How to present the information </li></ul><li>Pracitcal Limitations </li><ul><li>Length, completeness, file size, etc. </li></ul></ul>
  5. 5. Writing Challenges: Other Sources <ul><li>Everything we cover is already documented
  6. 6. Many other sources </li><ul><li>Ubuntu documentation
  7. 7. GNOME documentation
  8. 8. Community and user documentation and guides </li></ul><li>Problems </li><ul><li>Task-based versus guided help
  9. 9. Licensing is incompatible
  10. 10. Technical level is too high </li></ul></ul>
  11. 11. Our Audience: New Users <ul><li>People who are new to Linux and Ubuntu
  12. 12. May be new computer users
  13. 13. Assume basic keyboard and mouse skills, concept of a modern GUI with overlapping windows
  14. 14. Do not know other terms </li><ul><li>computer vs. monitor
  15. 15. ethernet vs. wifi
  16. 16. IMAP vs. POP
  17. 17. sudo vs. root </li></ul></ul>
  18. 18. Our Audience: New Users <ul><li>Do not use any technical jargon
  19. 19. Define or explain everything more difficult than clicking the mouse button
  20. 20. Be very precise in your language to make sure the user knows what you are describing </li><ul><li>Know UI widget names and actions </li></ul><li>Start with the simple, end with the advanced </li></ul>
  21. 21. Our Audience: Eager To Learn <ul><li>Interested in learning
  22. 22. Task oriented, wants to know how to: </li><ul><li>Browse the web
  23. 23. Scan a document
  24. 24. Edit spreadsheets
  25. 25. Keep the system up to date </li></ul><li>May read the manual in large chunks, not purely as a reference work but as a book </li></ul>
  26. 26. Our Audience: Eager to Learn <ul><li>Keep a narrative that turns a novice into a knowledgeable user
  27. 27. Think in terms of user tasks, not technology </li><ul><li>Each documented action should be attributed to a potential user desire </li></ul><li>Use asides and margins to inform users about advanced topics, or how to learn more
  28. 28. Do not patronize </li></ul>
  29. 29. Our Audience: International <ul><li>Core language for the manual is English... </li><ul><li>...but we're translating into tens of other languages </li></ul><li>Even for the English version, need to assume an international audience </li><ul><li>Some may not have English as their first language, and may not be fluent in it </li></ul><li>Idioms, humor, complex vocabulary will cause problems </li></ul>
  30. 30. Our Audience: International <ul><li>Use very, very simple language
  31. 31. Always use a simpler synonym
  32. 32. Repeat yourself </li><ul><li>In Ubuntu, you can do X with Y. To do X, … </li></ul><li>Use short paragraphs with a few sentences in each one
  33. 33. All English-language documentation for Ubuntu uses American spelling </li></ul>
  34. 34. Our Voice: Confident <ul><li>Our users expect us to be experts on Ubuntu
  35. 35. In writing, we need to be confident of our opinions </li><ul><li>Wrong: 'Ubuntu is reasonably secure'
  36. 36. Correct: 'Ubuntu is a secure operating system' </li></ul><li>But we shouldn't claim to be prescient </li><ul><li>Worse: 'Ubuntu will open a window'
  37. 37. Better: 'Ubuntu should open a window' </li></ul></ul>
  38. 38. Our Voice: Direct and Calm <ul><li>Write as if you are having a conversation with the reader </li><ul><li>Wrong: “Those with Gmail accounts can...”
  39. 39. Correct: “If you have a Gmail account, you can...” </li></ul><li>Avoid superlatives and marketing speak </li><ul><li>“Ubuntu is the best at...”
  40. 40. “The easiest way...”
  41. 41. “Ubuntu is excellent at...” </li></ul></ul>
  42. 42. Our Voice: Slightly Opinionated <ul><li>There is always more than one way to do it
  43. 43. But we should only recommend one or two </li><ul><li>Consistency with official documentation
  44. 44. Don't mention other options unless they are actually better , not just because they exist
  45. 45. OK to have both mouse & keyboard directions </li></ul><li>Try to steer users away from bad decisions, but do not preach </li><ul><li>provide reasons why something is a good idea </li></ul></ul>
  46. 46. Our Voice: Aligned with Users <ul><li>Think of how users will want to use what you are describing </li><ul><li>Title each section with a verb in gerund form </li><ul><li>“ Customizing the desktop”, “Scanning images”, “Securing your network connection” etc. </li></ul></ul><li>Guide them from justifying the need to completing the task </li><ul><li>Start with why they may want to do it, and give detailed steps until you lead them to the end </li></ul></ul>
  47. 47. Conventions: Attribution <ul><li>Policy is to to use Ubuntu, not Linux, in copy </li><ul><li>Anything else will confuse users </li></ul><li>Attribute desktop actions to Ubuntu, application actions to the application </li><ul><li>“Ubuntu will open the help window...”
  48. 48. “Empathy will open a window...” </li></ul><li>Ensure active voice </li><ul><li>Good: “Empathy will open a window...”
  49. 49. Bad: “A window will be opened by Empathy” </li></ul></ul>
  50. 50. Conventions: Standard GUI Terms <ul><li>button </li><ul><li>Click OK, Cancel, other common buttons
  51. 51. Click on other buttons </li></ul><li>check box </li><ul><li>Two words
  52. 52. Choose , or select / deselect
  53. 53. A check box is either selected or unselected
  54. 54. Can also write “option” instead of “check box” </li></ul></ul>
  55. 55. Conventions: Standard GUI Terms <ul><li>dialog </li><ul><li>Not “dialog box”
  56. 56. The name of the dialog is its title </li></ul><li>drop-down list </li><ul><li>One that does not let you type
  57. 57. Use the name drop-down list to specify </li></ul><li>drop-down combination list </li><ul><li>One that lets you type
  58. 58. Not “combo box” </li></ul></ul>
  59. 59. Conventions: Standard GUI Terms <ul><li>double-click </li><ul><li>Spell with a dash
  60. 60. double-click on something </li></ul><li>drag </li><ul><li>Do not use “drag and drop”
  61. 61. drag something to some place </li></ul></ul>
  62. 62. Conventions: Standard GUI Terms <ul><li>field </li><ul><li>Enter information in the name field </li></ul><li>list box </li><ul><li>Select or choose </li></ul><li>Main Menu </li><ul><li>The GNOME desktop's main menu </li></ul><li>menubar </li><ul><li>One word, not two
  63. 63. Choose from a menubar </li></ul></ul>
  64. 64. Conventions: Standard GUI Terms <ul><li>Log in, log out, shut down </li><ul><li>Two words for actions </li></ul><li>Login, shutdown </li><ul><li>One word for nouns/adjectives </li></ul><li>popup menu </li><ul><li>Not “pop-up” </li></ul><li>radio button </li><ul><li>Use “option” instead
  65. 65. Choose or select </li></ul></ul>
  66. 66. Conventions: Standard GUI Terms <ul><li>scrollbar, statusbar, titlebar, toolbar </li><ul><li>One word </li></ul><li>tab </li><ul><li>Click on a tab </li></ul><li>text box </li><ul><li>Use the text box to specify </li></ul></ul>