Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

User Love and how to get it through good documentation

939 views

Published on

It is a well-acknowledged fact that users love good documentation. It is a less well known fact that developers love good documentation too. This talk, aimed at developers, shows why you should love good documentation, and proves that it's not difficult to write. It also explains what tools you should use and a couple of points on how to make documentation that users will want to help write.

Published in: Technology
  • Be the first to comment

  • Be the first to like this

User Love and how to get it through good documentation

  1. 1. User Love and how to get it
  2. 2. User Love and how to get it through good Documentation
  3. 3. Facts and Stories
  4. 4. Story
  5. 5. LMMS original documentation
  6. 6. LMMS original documentation <ul><li>What was wrong? </li></ul>
  7. 7. LMMS original documentation <ul><li>What was wrong? </li></ul><ul><ul><li>Barely any content </li></ul></ul>
  8. 8. LMMS original documentation <ul><li>What was wrong? </li></ul><ul><ul><li>Barely any content </li></ul></ul><ul><ul><li>Description of the trivial </li></ul></ul>
  9. 9. LMMS original documentation <ul><li>What was wrong? </li></ul><ul><ul><li>Barely any content </li></ul></ul><ul><ul><li>Description of the trivial </li></ul></ul><ul><ul><li>Loosely coupled </li></ul></ul>
  10. 10. Ask the Developers
  11. 11. Ask the Developers <ul><li>Fix the bugs </li></ul>
  12. 12. Ask the Developers <ul><li>Fix the bugs </li></ul><ul><li>Add more features </li></ul>
  13. 13. Ask the Developers <ul><li>Fix the bugs </li></ul><ul><li>Add more features </li></ul><ul><li>Update the documentation!!!! </li></ul>
  14. 14. Developer problems
  15. 15. Developer problems <ul><li>Users asking stupid questions </li></ul>
  16. 16. Developer problems <ul><li>Users asking stupid questions </li></ul><ul><li>Fixing bugs more important </li></ul>
  17. 17. Developer problems <ul><li>Users asking stupid questions </li></ul><ul><li>Fixing bugs more important </li></ul><ul><li>One developer </li></ul>
  18. 18. LMMS – the self help guide <ul><li>My decision: write the documentation </li></ul>
  19. 19. LMMS – the self help guide <ul><li>My decision: write the documentation </li></ul><ul><ul><li>I was the one asking stupid questions </li></ul></ul>
  20. 20. LMMS – the self help guide <ul><li>My decision: write the documentation </li></ul><ul><ul><li>I was the one asking stupid questions </li></ul></ul><ul><ul><li>Documentation helps other users learn </li></ul></ul>
  21. 21. LMMS – the self help guide <ul><li>My decision: write the documentation </li></ul><ul><ul><li>I was the one asking stupid questions </li></ul></ul><ul><ul><li>Documentation helps other users learn </li></ul></ul><ul><ul><li>Learn more about the program </li></ul></ul>
  22. 22. LMMS – the self help guide <ul><li>My decision: write the documentation </li></ul><ul><ul><li>I was the one asking stupid questions </li></ul></ul><ul><ul><li>Documentation helps other users learn </li></ul></ul><ul><ul><li>Learn more about the program </li></ul></ul><ul><ul><li>Quid pro quo code writing </li></ul></ul>
  23. 23. Facts
  24. 24. Fact 1: Users Love Documentation
  25. 25. Users Love Documentation cayusa : golden compass - http://flickr.com/photos/cayusa/2061945970/
  26. 26. Fact 1: Users Love Good Documentation
  27. 27. Users Love Good Documentation cayusa : golden compass - http://flickr.com/photos/cayusa/2061945970/
  28. 28. Fact 2: Developers Love Good Documentation
  29. 29. Developers Love Good Documentation <ul><li>Users can learn for themselves </li></ul>rogimmi : manifestazione- http://flickr.com/photos/rogimmi/2385263392/
  30. 30. Developers Love Good Documentation <ul><li>Users can learn for themselves </li></ul><ul><li>Users can answer other users questions </li></ul>thesheriff : telling a secret - http://flickr.com/photos/thesheriff/194236786/
  31. 31. Developers Love Good Documentation <ul><li>Users can learn for themselves </li></ul><ul><li>Users can answer other users questions </li></ul><ul><li>Users write their own documentation </li></ul>tizzie : the greatest book - http://flickr.com/photos/tizzie/65362232/
  32. 32. Developers Love Good Documentation <ul><li>Users can learn for themselves </li></ul><ul><li>Users can answer other users questions </li></ul><ul><li>Users write their own documentation </li></ul><ul><li>Users go on to be Developers </li></ul>michale : girl power - http://flickr.com/photos/michale/238445168/
  33. 33. Starting the documentation <ul><li>What did I want? </li></ul>
  34. 34. Starting the documentation <ul><li>What did I want? </li></ul><ul><ul><li>Everything I didn't know </li></ul></ul>
  35. 35. Starting the documentation <ul><li>What did I want? </li></ul><ul><ul><li>Everything I didn't know: </li></ul></ul><ul><ul><ul><li>Instrument tutorials </li></ul></ul></ul>
  36. 36. Starting the documentation <ul><li>What did I want? </li></ul><ul><ul><li>Everything I didn't know: </li></ul></ul><ul><ul><ul><li>Instrument tutorials </li></ul></ul></ul><ul><ul><ul><li>What could automation do </li></ul></ul></ul>
  37. 37. Starting the documentation <ul><li>What did I want? </li></ul><ul><ul><li>Everything I didn't know: </li></ul></ul><ul><ul><ul><li>Instrument tutorials </li></ul></ul></ul><ul><ul><ul><li>What could automation do </li></ul></ul></ul><ul><ul><ul><li>Full reference for the controls </li></ul></ul></ul>
  38. 38. Starting the documentation <ul><li>What did I want? </li></ul><ul><ul><li>Everything I didn't know: </li></ul></ul><ul><ul><ul><li>Instrument tutorials </li></ul></ul></ul><ul><ul><ul><li>What could automation do </li></ul></ul></ul><ul><ul><ul><li>Full reference for the controls </li></ul></ul></ul><ul><ul><ul><li>Organised roadmap </li></ul></ul></ul>
  39. 39. Starting the documentation <ul><li>What did other people want? </li></ul>
  40. 40. Starting the documentation <ul><li>What did other people want? </li></ul><ul><ul><li>Everything they didn't know: </li></ul></ul><ul><ul><ul><li>Tutorial on how to make a new song </li></ul></ul></ul><ul><ul><ul><li>Detailed look at the ways to use instruments </li></ul></ul></ul><ul><ul><ul><li>Full reference for the menus </li></ul></ul></ul><ul><ul><ul><li>Ponies and kittens living together </li></ul></ul></ul>
  41. 41. Starting the documentation <ul><li>What did we all want? </li></ul>
  42. 42. Starting the documentation <ul><li>Who is this 'we' anyway? </li></ul>
  43. 43. Fact 3: There are different types of user futureshape : interesting crowd - http://flickr.com/photos/futureshape/2620528647/
  44. 44. Fact 3a: There are different types of documentation heliocentric : reading stack - http://flickr.com/photos/heliocentric/528094587/
  45. 45. Different users <ul><li>Novices </li></ul>wiccked : riding a bike - http://flickr.com/photos/wiccked/358029324/
  46. 46. Different users <ul><li>Novices </li></ul><ul><li>Intermediate </li></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  47. 47. Different users <ul><li>Novices </li></ul><ul><li>Intermediate </li></ul><ul><li>Advanced </li></ul>ross : experts only - http://flickr.com/photos/ross/4368015/
  48. 48. Different documentation <ul><li>Novices </li></ul><ul><ul><li>Tutorials </li></ul></ul><ul><ul><li>How Tos </li></ul></ul><ul><ul><li>Quick start guides </li></ul></ul>wiccked : riding a bike - http://flickr.com/photos/wiccked/358029324/
  49. 49. Different documentation <ul><li>Advanced </li></ul><ul><ul><li>References </li></ul></ul><ul><ul><li>API specs </li></ul></ul><ul><ul><li>Implementation details </li></ul></ul><ul><ul><li>Black voodoo </li></ul></ul>ross : experts only - http://flickr.com/photos/ross/4368015/
  50. 50. Different documentation <ul><li>Intermediate </li></ul><ul><ul><li>Subject guides </li></ul></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  51. 51. Different documentation <ul><li>Intermediate </li></ul><ul><ul><li>Subject guides How to achieve particular tasks using all relevant features of your program </li></ul></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  52. 52. Different documentation <ul><li>Intermediate </li></ul><ul><ul><li>Subject guides What are these “tasks”? </li></ul></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  53. 53. Different documentation <ul><li>Intermediate </li></ul><ul><ul><li>Subject guides </li></ul></ul><ul><ul><li>Look for related tools </li></ul></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  54. 54. Different documentation <ul><li>Intermediate </li></ul><ul><ul><li>Subject guides </li></ul></ul><ul><ul><li>Look for related tools </li></ul></ul><ul><ul><li>Look for related goals </li></ul></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  55. 55. Different documentation <ul><li>Intermediate </li></ul><ul><ul><li>Subject guides </li></ul></ul><ul><ul><li>Look for related tools </li></ul></ul><ul><ul><li>Look for related goals </li></ul></ul><ul><ul><li>“ Tips and Tricks” </li></ul></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  56. 56. Different documentation <ul><li>Intermediate </li></ul><ul><ul><li>Subject guides </li></ul></ul><ul><ul><li>Look for related tools </li></ul></ul><ul><ul><li>Look for related goals </li></ul></ul><ul><ul><li>“ Tips and Tricks” </li></ul></ul><ul><ul><li>Extensible list </li></ul></ul>whyisjake : ski runs - http://flickr.com/photos/whyisjake/3089679612/
  57. 57. Different documentation <ul><li>Intermediate </li></ul>
  58. 58. Different documentation <ul><li>Novices Intermediate Advanced </li></ul><ul><li>Tutorial Subject guides Reference </li></ul>wnorrix : pre group photo – IndLinux 2005 - http://flickr.com/photos/wnorrix/43845049/
  59. 59. Different documentation <ul><li>Novices Intermediate Advanced </li></ul><ul><li>How? Why? What? </li></ul>wnorrix : pre group photo – IndLinux 2005 - http://flickr.com/photos/wnorrix/43845049/
  60. 60. Fact 4: Good Documentation is not hard to write dey : serious child – http://flickr.com/photos/dey/69542427/
  61. 61. Writing Documentation <ul><li>It was a dark and stormy night; the rain fell in torrents – except at occasional intervals, when it was checked by a violent gust of wind which swept up the streets (for it is in London that our scene lies), rattling along the housetops, and fiercely agitating the scanty flame of the lamps that struggled against the darkness. </li></ul>
  62. 62. Writing Documentation <ul><li>Far out in the uncharted backwaters of the unfashionable end of the western spiral arm of the Galaxy lies a small unregarded yellow sun. </li></ul>
  63. 63. Documentation is just another project
  64. 64. How do you normally write code?
  65. 65. Approaches to Programming <ul><li>Top down </li></ul><ul><ul><li>Plan overall structure </li></ul></ul><ul><ul><li>Break modules down into submodules </li></ul></ul><ul><ul><li>Eventually get to real module code </li></ul></ul>
  66. 66. Approaches to Programming <ul><li>Top down </li></ul><ul><li>Bottom up </li></ul><ul><ul><li>Write known code for actual features </li></ul></ul><ul><ul><li>Make modules that join features together </li></ul></ul><ul><ul><li>Integrate modules into overall structure </li></ul></ul>
  67. 67. Approaches to Programming <ul><li>Top down </li></ul><ul><li>Bottom up </li></ul><ul><li>Both at the same time </li></ul><ul><ul><li>Plan overall structure </li></ul></ul><ul><ul><li>Write code for either top or bottom levels </li></ul></ul><ul><ul><li>Modules and features meet in the middle </li></ul></ul>
  68. 68. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><ul><li>Plan overall structure </li></ul></ul><ul><ul><li>Divide up chapters into sections or </li></ul></ul><ul><ul><li>Write sections </li></ul></ul><ul><ul><li>Documentation meets in the middle </li></ul></ul>
  69. 69. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><ul><li>Plan overall structure – Table of Contents </li></ul></ul><ul><ul><ul><li>Introduction </li></ul></ul></ul><ul><ul><ul><li>Tutorials </li></ul></ul></ul><ul><ul><ul><li>Subject Guides </li></ul></ul></ul><ul><ul><ul><li>References </li></ul></ul></ul><ul><ul><ul><li>Appendices </li></ul></ul></ul>
  70. 70. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><ul><li>Plan overall structure – Table of Contents </li></ul></ul><ul><ul><ul><li>Introduction </li></ul></ul></ul><ul><ul><ul><ul><li>Requirements, Installation, Terms and Conventions </li></ul></ul></ul></ul><ul><ul><ul><li>Tutorials </li></ul></ul></ul><ul><ul><ul><li>Subject Guides </li></ul></ul></ul><ul><ul><ul><li>References </li></ul></ul></ul><ul><ul><ul><li>Appendices </li></ul></ul></ul><ul><ul><ul><ul><li>Glossary, Key Shortcuts, License, Roadmap, ... </li></ul></ul></ul></ul>
  71. 71. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul>
  72. 72. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><ul><li>Start with what you know </li></ul></ul>
  73. 73. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><ul><li>Start with what you know </li></ul></ul><ul><ul><li>Write in small increments </li></ul></ul>
  74. 74. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><ul><li>Start with what you know </li></ul></ul><ul><ul><li>Write in small increments </li></ul></ul><ul><ul><li>Reward yourself for good work </li></ul></ul>
  75. 75. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><ul><li>Start with what you know </li></ul></ul><ul><ul><li>Write in small increments </li></ul></ul><ul><ul><li>Reward yourself for good work </li></ul></ul><ul><ul><li>Save favourite sections for writers' block </li></ul></ul>
  76. 76. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><li>Be consistent </li></ul>
  77. 77. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><li>Be consistent </li></ul><ul><ul><li>Glossary / Terms and Conventions </li></ul></ul>
  78. 78. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><li>Be consistent </li></ul><ul><ul><li>Glossary / Terms and Conventions </li></ul></ul><ul><ul><li>Layout and formatting </li></ul></ul>
  79. 79. Approaches to Documentation <ul><li>Both at the same time </li></ul><ul><li>Write! </li></ul><ul><li>Be consistent </li></ul><ul><ul><li>Glossary / Terms and Conventions </li></ul></ul><ul><ul><li>Layout and formatting </li></ul></ul><ul><ul><li>Don't be afraid to rewrite </li></ul></ul>
  80. 80. LMMS Documentation examples
  81. 81. LMMS Documentation examples
  82. 82. LMMS Documentation examples
  83. 83. Fact 5: Only one tool... chazferret : framing hammer collection - http://flickr.com/photos/chazferret/2658412857/
  84. 84. Fact 5: Use a Wiki chazferret : framing hammer collection - http://flickr.com/photos/chazferret/2658412857/
  85. 85. Documenting on a Wiki <ul><li>Simple editing from anywhere </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  86. 86. Documenting on a Wiki <ul><li>Simple editing from anywhere </li></ul><ul><li>Cross-referencing </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  87. 87. Documenting on a Wiki <ul><li>Simple editing from anywhere </li></ul><ul><li>Cross-referencing </li></ul><ul><li>Revision view and control </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  88. 88. Documenting on a Wiki <ul><li>Simple editing from anywhere </li></ul><ul><li>Cross-referencing </li></ul><ul><li>Revision view and control </li></ul><ul><li>Collaboration – many editors </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  89. 89. Documenting on a Wiki <ul><li>Simple editing from anywhere </li></ul><ul><li>Cross-referencing </li></ul><ul><li>Revision view and control </li></ul><ul><li>Collaboration – many editors </li></ul><ul><li>Googleable </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  90. 90. What you want from a Wiki jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  91. 91. What you want from a Wiki <ul><li>[[ComplexLink Link to a complex page]] </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  92. 92. What you want from a Wiki <ul><li>[[ComplexLink Link to a complex page]] </li></ul><ul><li>[[http://example.com/images/splash.png]] </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  93. 93. What you want from a Wiki <ul><li>[[ComplexLink Link to a complex page]] </li></ul><ul><li>[[http://example.com/images/splash.png]] </li></ul><ul><li>http://example.com/wiki/ComplexPage </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  94. 94. What you want from a Wiki <ul><li>[[ComplexLink Link to a complex page]] </li></ul><ul><li>[[http://example.com/images/splash.png]] </li></ul><ul><li>http://example.com/wiki/ComplexPage </li></ul><ul><li>http://example.com/wiki/en/0.3/Contents </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/
  95. 95. What you want from a Wiki <ul><li>[[ComplexLink Link to a complex page]] </li></ul><ul><li>[[http://example.com/images/splash.png]] </li></ul><ul><li>http://example.com/wiki/ComplexPage </li></ul><ul><li>http://example.com/wiki/en/0.3/Contents </li></ul><ul><li>LADSPA </li></ul>jdlasica : wiki wiki – http://flickr.com/photos/jdlasica/413488042/ [1]
  96. 96. Fact 6 Style matters og2t : scotland with style – http://flickr.com/photos/og2t/89821504/
  97. 97. Writing Style
  98. 98. Writing style <ul><li>Clean </li></ul><ul><li>Concise </li></ul><ul><li>Precise </li></ul><ul><li>Literate </li></ul><ul><li>Correct </li></ul>
  99. 99. Writing style <ul><li>Clean </li></ul><ul><ul><li>Visually simple and appealing </li></ul></ul><ul><ul><li>Not distracting </li></ul></ul><ul><li>Concise </li></ul><ul><li>Precise </li></ul><ul><li>Literate </li></ul><ul><li>Correct </li></ul>
  100. 100. Writing style <ul><li>Clean </li></ul><ul><li>Concise </li></ul><ul><ul><li>Say no more than you need to </li></ul></ul><ul><ul><li>Look for simpler ways of expressing yourself </li></ul></ul><ul><li>Precise </li></ul><ul><li>Literate </li></ul><ul><li>Correct </li></ul>
  101. 101. Writing style <ul><li>Clean </li></ul><ul><li>Concise </li></ul><ul><li>Precise </li></ul><ul><ul><li>Unambiguous and consistent </li></ul></ul><ul><ul><li>Distinguish between similar concepts / terms </li></ul></ul><ul><li>Literate </li></ul><ul><li>Correct </li></ul>
  102. 102. Writing style <ul><li>Clean </li></ul><ul><li>Concise </li></ul><ul><li>Precise </li></ul><ul><li>Literate </li></ul><ul><ul><li>Spelling, punctuation, grammar </li></ul></ul><ul><ul><li>Easy to read </li></ul></ul><ul><li>Correct </li></ul>
  103. 103. Writing style <ul><li>Clean </li></ul><ul><li>Concise </li></ul><ul><li>Precise </li></ul><ul><li>Literate </li></ul><ul><li>Correct </li></ul><ul><ul><li>Must accurately reflect state of program </li></ul></ul><ul><ul><li>Kept up to date </li></ul></ul>
  104. 104. Get the facts <ul><li>Users love good documentation </li></ul>
  105. 105. Get the facts <ul><li>Users love good documentation </li></ul><ul><li>Developers love good documentation </li></ul>
  106. 106. Get the facts <ul><li>Users love good documentation </li></ul><ul><li>Developers love good documentation </li></ul><ul><li>Different documentation for different users </li></ul>
  107. 107. Get the facts <ul><li>Users love good documentation </li></ul><ul><li>Developers love good documentation </li></ul><ul><li>Different documentation for different users </li></ul><ul><li>Documentation isn't hard to write </li></ul>
  108. 108. Get the facts <ul><li>Users love good documentation </li></ul><ul><li>Developers love good documentation </li></ul><ul><li>Different documentation for different users </li></ul><ul><li>Documentation isn't hard to write </li></ul><ul><li>Use a wiki </li></ul>
  109. 109. Get the facts <ul><li>Users love good documentation </li></ul><ul><li>Developers love good documentation </li></ul><ul><li>Different documentation for different users </li></ul><ul><li>Documentation isn't hard to write </li></ul><ul><li>Use a wiki </li></ul><ul><li>Style matters </li></ul>
  110. 110. Do you have time?
  111. 111. Do you have time? <ul><li>I don't have time to write a test! </li></ul>
  112. 112. Do you have time? <ul><li>I don't have time to write a test! </li></ul><ul><li>I don't have time to add a ticket! </li></ul>
  113. 113. Do you have time? <ul><li>I don't have time to write a test! </li></ul><ul><li>I don't have time to add a ticket! </li></ul><ul><li>I don't have time to write documentation! </li></ul>
  114. 114. Yes! You have time!
  115. 115. Yes! You have time! Write good documentation!
  116. 116. Questions?
  117. 117. http://lmms.sourceforge.net

×