Documentation: get it right!

ApacheCon Europe 2009
Amsterdam


                        Niels van Kampenhout
             ...
About me

My name is Niels van Kampenhout
I work for Hippo
My responsibilities include documentation
and training
I am a t...
This talk

   A user's perspective on documentation
   within Apache
   General observations
   How I think documentation ...
Me and documentation

   I'm not really a technical writer
   I kind of became one by chance
   Common sense, trial and er...
Open source and documentation

   Bad reputation
   It may not be that bad...
   ... but there is definitely room for
   i...
Why good documentation is important

   Adoption
   “Non open source people” have certain
   expectations




03/25/09    ...
Documentation within Apache

   Is it really that bad?
   There is a lot of documentation, but...
       Focus on develope...
The excuses

   It's open source, read the code!
   I don't have time to write
   documentation!
   I hate Xdoc/JSPWiki/.....
The real reasons

   Developers are generally not good
   documentation writers
   They're deep in code, find it difficult...
The real reasons

   Writing documentation is not sexy
   Why write documentation if you can fix
   a bug or implement a n...
The real reasons

   Fragmentation
       Mailing lists
       Wikis
       Subprojects
   For an outsider it is hard to g...
What can we do about it?

   Take a step back




03/25/09                                      12
               Document...
Be realistic

   Don't expect developers to write good
   documentation




03/25/09                                      ...
Divide and conquer

   Make one person responsible for
   documentation (the “doctator”)
   Doctator has overview, organiz...
Embrace your users

   Users are often the best people to
   write user documentation
   They know what they want to achie...
Embrace your users

   Make use of your community
   Encourage users to contribute
   documentation
   Guide documentation...
Embrace your users

   Have the right attitude towards your
   users
   “RTFM” ?
       Review The F***ing Manual!
   “We ...
Organizing your documentation

   Think about who will use your software,
   and what they want to achieve with it
   Writ...
Cater to your users

   Provide different tracks for different
   users and different goals
   Think about what to put in ...
Provide introductory documentation

   Introduce the reader to your project
   Describe in a few sentences what it is
   S...
Give your readers some context

   What do they need to know?
   What are they going to achieve?
   Where should they go n...
Respect your readers

   Your readers are smart people
   Don't force them to read what they
   don't need to know
   Don'...
Think about the Big Picture

   Don't only look at your project
   Be conservative in referring to other
   projects' docu...
Examples Examples Examples!

   Use lots of examples
   But make sure readers can easily
   reproduce them




03/25/09   ...
Screenshots

   Screenshots should clarify, not distract!
   Leave out irrelevant stuff
   Use consistent resolution and t...
Reference guide

   Provide a reference guide
   Glossary, concepts, fundamentals, syntax
   Complements “howto” style gui...
Be specific about versions

   Always mention what version this
   documentation applies to
   Never refer to a version as...
Test the documentation

   Try it out yourself, you might be
   surprised!
   Even better, have others test it
   Do it fr...
Watch out for outdated documentation

   Take outdated docs offline until they
   are updated
   Or update them right away...
About documentation tools

   The tools you use should not be an
   excuse not to write documentation
   Wikis are great f...
The devil is in the details

   Consistency
       Terminology
       Screenshots
   Completeness
       If your give code...
Conclusion

   Producing decent documentation is not
   rocket science
   It just takes a lot of time
   But it's worth th...
Upcoming SlideShare
Loading in …5
×

Documentation: get it right! (ApacheCon EU 2009)

1,183 views

Published on

Published in: Technology
0 Comments
2 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total views
1,183
On SlideShare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
26
Comments
0
Likes
2
Embeds 0
No embeds

No notes for slide

Documentation: get it right! (ApacheCon EU 2009)

  1. Documentation: get it right! ApacheCon Europe 2009 Amsterdam Niels van Kampenhout “Doctator” Hippo Amsterdam/San Francisco
  2. About me My name is Niels van Kampenhout I work for Hippo My responsibilities include documentation and training I am a typical “user” within Apache
  3. This talk A user's perspective on documentation within Apache General observations How I think documentation should be done Not a writing course 03/25/09 3 Documentation: get it right!
  4. Me and documentation I'm not really a technical writer I kind of became one by chance Common sense, trial and error I train people to use Apache software I see how these people approach open source software 03/25/09 4 Documentation: get it right!
  5. Open source and documentation Bad reputation It may not be that bad... ... but there is definitely room for improvement! 03/25/09 5 Documentation: get it right!
  6. Why good documentation is important Adoption “Non open source people” have certain expectations 03/25/09 6 Documentation: get it right!
  7. Documentation within Apache Is it really that bad? There is a lot of documentation, but... Focus on developers Inconsistent Fragmented Folks outside Apache expect something more coherent, more guiding 03/25/09 7 Documentation: get it right!
  8. The excuses It's open source, read the code! I don't have time to write documentation! I hate Xdoc/JSPWiki/... We have documentation, stop complaining! We won't sell any training courses! 03/25/09 8 Documentation: get it right!
  9. The real reasons Developers are generally not good documentation writers They're deep in code, find it difficult to step back to get an overview They're perfectionists Their talent is in coding, not in writing documentation 03/25/09 9 Documentation: get it right!
  10. The real reasons Writing documentation is not sexy Why write documentation if you can fix a bug or implement a new feature? 03/25/09 10 Documentation: get it right!
  11. The real reasons Fragmentation Mailing lists Wikis Subprojects For an outsider it is hard to get an overview 03/25/09 11 Documentation: get it right!
  12. What can we do about it? Take a step back 03/25/09 12 Documentation: get it right!
  13. Be realistic Don't expect developers to write good documentation 03/25/09 13 Documentation: get it right!
  14. Divide and conquer Make one person responsible for documentation (the “doctator”) Doctator has overview, organizes Relieve (other) developers from writing, just let them write down 03/25/09 14 Documentation: get it right!
  15. Embrace your users Users are often the best people to write user documentation They know what they want to achieve with your software There's a whole user list of them! 03/25/09 15 Documentation: get it right!
  16. Embrace your users Make use of your community Encourage users to contribute documentation Guide documentation writing users towards committership 03/25/09 16 Documentation: get it right!
  17. Embrace your users Have the right attitude towards your users “RTFM” ? Review The F***ing Manual! “We do this in our own time” Users do it in their own time too you know! 03/25/09 17 Documentation: get it right!
  18. Organizing your documentation Think about who will use your software, and what they want to achieve with it Write for a target audience Write to let the reader achieve something Validate your assumptions, ask your users! 03/25/09 18 Documentation: get it right!
  19. Cater to your users Provide different tracks for different users and different goals Think about what to put in a track ... ... and what to leave out Tracks can share content But be careful not to let a user end up in a different track 03/25/09 19 Documentation: get it right!
  20. Provide introductory documentation Introduce the reader to your project Describe in a few sentences what it is State what problem it is meant to solve Try to avoid acronyms, jargon A picture is worth a thousand words 03/25/09 20 Documentation: get it right!
  21. Give your readers some context What do they need to know? What are they going to achieve? Where should they go next? Don't expect your readers to start on the homepage / table of contents 03/25/09 21 Documentation: get it right!
  22. Respect your readers Your readers are smart people Don't force them to read what they don't need to know Don't talk to them as if they're children Imagine yourself in the reader's place 03/25/09 22 Documentation: get it right!
  23. Think about the Big Picture Don't only look at your project Be conservative in referring to other projects' documentation Try not to fragment your documentation 03/25/09 23 Documentation: get it right!
  24. Examples Examples Examples! Use lots of examples But make sure readers can easily reproduce them 03/25/09 24 Documentation: get it right!
  25. Screenshots Screenshots should clarify, not distract! Leave out irrelevant stuff Use consistent resolution and theme Use consistent language settings Set up a VM with default OS/browser settings 03/25/09 25 Documentation: get it right!
  26. Reference guide Provide a reference guide Glossary, concepts, fundamentals, syntax Complements “howto” style guides Refer to/from tutorials and examples 03/25/09 26 Documentation: get it right!
  27. Be specific about versions Always mention what version this documentation applies to Never refer to a version as “latest” or “current” Screenshots should reflect the version the documentation applies to 03/25/09 27 Documentation: get it right!
  28. Test the documentation Try it out yourself, you might be surprised! Even better, have others test it Do it frequently, at least before each release 03/25/09 28 Documentation: get it right!
  29. Watch out for outdated documentation Take outdated docs offline until they are updated Or update them right away! Leaving outdated docs online will bounce back to you 03/25/09 29 Documentation: get it right!
  30. About documentation tools The tools you use should not be an excuse not to write documentation Wikis are great for initial ideas and user contributions, but they should be maintained Ultimately you will want a CMS 03/25/09 30 Documentation: get it right!
  31. The devil is in the details Consistency Terminology Screenshots Completeness If your give code examples, make sure readers know what to do with them Test for dead links 03/25/09 31 Documentation: get it right!
  32. Conclusion Producing decent documentation is not rocket science It just takes a lot of time But it's worth the effort Happy users -> Adoption User involvement Healthy community 03/25/09 32 Documentation: get it right!

×