Writing Beautiful Technical Documentation

4,027 views

Published on

Subtitled: "Writing FOSS Docs That Don't Suck"

A look at why documentation is so important for open source projects, and how to create documentation that does wonders for your project.

Created for linux.conf.au 2010 in Wellington

Published in: Technology, Business
0 Comments
3 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
4,027
On SlideShare
0
From Embeds
0
Number of Embeds
25
Actions
Shares
0
Downloads
59
Comments
0
Likes
3
Embeds 0
No embeds

No notes for slide

Writing Beautiful Technical Documentation

  1. 1. Creating Beautiful Open Source Technical Documentation Or: Writing FOSS Docs that Don't Suck
  2. 4. Technical Writing A Fairy Tale
  3. 5. A long time ago in a galaxy far far away ...
  4. 6. Jane
  5. 7. Fred Sue Bob
  6. 8. Monday
  7. 9. Tuesday
  8. 10. Tuesday My l337 db rawks!
  9. 11. Wednesday
  10. 12. Wednesday My h4X0r skills are teh win!
  11. 13. Thursday
  12. 14. Thursday My design skillz are made of awesome!
  13. 15. Friday
  14. 16. Friday WTF?!
  15. 17. Friday
  16. 18. Friday My l337 db rawks!
  17. 19. Friday My h4X0r skills are teh win!
  18. 20. Friday All users base are belong to us
  19. 21. Friday
  20. 22. Saturday
  21. 23. Sunday
  22. 24. Monday Ship it!
  23. 25. Tuesday
  24. 26. Wednesday
  25. 27. Thursday
  26. 28. Thursday ???
  27. 29. Thursday !!!
  28. 30. Thursday $*!%
  29. 31. Friday Dole queue
  30. 32. Just because you can READ a manual ...
  31. 33. Doesn't mean you can write one.
  32. 34. Happily Ever After?
  33. 35. Information Plan Content Specification Writing Translation & Production Review Release 5 Phase Model by JoAnn Hackos
  34. 36. “ A common mistake that people make when trying to design something completely foolproof is to underestimate the ingenuity of complete fools ” Douglas Adams “Mostly Harmless”
  35. 42. How To: Write FOSS Docs that don't suck
  36. 43. no one reads manuals! But ...
  37. 44. Why Document?
  38. 45. What makes your software awesome?
  39. 46. These things all work the same for documentation
  40. 47. Learnability
  41. 48. Efficiency
  42. 49. Retention
  43. 50. Few user errors
  44. 51. Satisfaction
  45. 52. It's all about the user
  46. 53. Whoever they might be
  47. 54. When users love the software then that's great software!
  48. 55. But when they don't ... the documentation should be there to save you
  49. 56. Beautiful documentation won't make crappy software any better But it might prevent some users from trying to stab you
  50. 57. Lana Brindley Red Hat Technical Writer [email_address] +61 410 500 659 @Loquacities http://lanabrindley.blogspot.com/

×