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!