Niels van KampenhoutNiels van Kampenhout““Doctator”Doctator”
HippoHippoAmsterdam/San FranciscoAmsterdam/San Francisco
Documentation: get it right!Documentation: get it right!
ApacheCon Europe 2009ApacheCon Europe 2009AmsterdamAmsterdam
About me
My name is Niels van KampenhoutI work for HippoMy responsibilities include documentation and trainingI am a typical “user” within Apache
03/25/09 Documentation: get it right! 3
This talk
A user's perspective on documentation within ApacheGeneral observationsHow I think documentation should be doneNot a writing course
03/25/09 Documentation: get it right! 4
Me and documentation
I'm not really a technical writerI kind of became one by chanceCommon sense, trial and errorI train people to use Apache softwareI see how these people approach open source software
03/25/09 Documentation: get it right! 5
Open source and documentation
Bad reputationIt may not be that bad...... but there is definitely room for improvement!
03/25/09 Documentation: get it right! 6
Why good documentation is important
Adoption“Non open source people” have certain expectations
03/25/09 Documentation: get it right! 7
Documentation within Apache
Is it really that bad?There is a lot of documentation, but...Focus on developersInconsistentFragmented
Folks outside Apache expect something more coherent, more guiding
03/25/09 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 Documentation: get it right! 9
The real reasons
Developers are generally not good documentation writersThey're deep in code, find it difficult to step back to get an overviewThey're perfectionistsTheir talent is in coding, not in writing documentation
03/25/09 Documentation: get it right! 10
The real reasons
Writing documentation is not sexyWhy write documentation if you can fix a bug or implement a new feature?
03/25/09 Documentation: get it right! 11
The real reasons
FragmentationMailing listsWikisSubprojects
For an outsider it is hard to get an overview
03/25/09 Documentation: get it right! 12
What can we do about it?
Take a step back
03/25/09 Documentation: get it right! 13
Be realistic
Don't expect developers to write good documentation
03/25/09 Documentation: get it right! 14
Divide and conquer
Make one person responsible for documentation (the “doctator”)Doctator has overview, organizesRelieve (other) developers from writing, just let them write down
03/25/09 Documentation: get it right! 15
Embrace your users
Users are often the best people to write user documentationThey know what they want to achieve with your softwareThere's a whole user list of them!
03/25/09 Documentation: get it right! 16
Embrace your users
Make use of your communityEncourage users to contribute documentationGuide documentation writing users towards committership
03/25/09 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 Documentation: get it right! 18
Organizing your documentation
Think about who will use your software, and what they want to achieve with itWrite for a target audienceWrite to let the reader achieve somethingValidate your assumptions, ask your users!
03/25/09 Documentation: get it right! 19
Cater to your users
Provide different tracks for different users and different goalsThink about what to put in a track ...... and what to leave outTracks can share contentBut be careful not to let a user end up in a different track
03/25/09 Documentation: get it right! 20
Provide introductory documentation
Introduce the reader to your projectDescribe in a few sentences what it isState what problem it is meant to solveTry to avoid acronyms, jargonA picture is worth a thousand words
03/25/09 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 Documentation: get it right! 22
Respect your readers
Your readers are smart peopleDon't force them to read what they don't need to knowDon't talk to them as if they're childrenImagine yourself in the reader's place
03/25/09 Documentation: get it right! 23
Think about the Big Picture
Don't only look at your projectBe conservative in referring to other projects' documentationTry not to fragment your documentation
03/25/09 Documentation: get it right! 24
Examples Examples Examples!
Use lots of examplesBut make sure readers can easily reproduce them
03/25/09 Documentation: get it right! 25
Screenshots
Screenshots should clarify, not distract!Leave out irrelevant stuffUse consistent resolution and themeUse consistent language settingsSet up a VM with default OS/browser settings
03/25/09 Documentation: get it right! 26
Reference guide
Provide a reference guideGlossary, concepts, fundamentals, syntaxComplements “howto” style guidesRefer to/from tutorials and examples
03/25/09 Documentation: get it right! 27
Be specific about versions
Always mention what version this documentation applies toNever refer to a version as “latest” or “current”Screenshots should reflect the version the documentation applies to
03/25/09 Documentation: get it right! 28
Test the documentation
Try it out yourself, you might be surprised!Even better, have others test itDo it frequently, at least before each release
03/25/09 Documentation: get it right! 29
Watch out for outdated documentation
Take outdated docs offline until they are updatedOr update them right away!Leaving outdated docs online will bounce back to you
03/25/09 Documentation: get it right! 30
About documentation tools
The tools you use should not be an excuse not to write documentationWikis are great for initial ideas and user contributions, but they should be maintainedUltimately you will want a CMS
03/25/09 Documentation: get it right! 31
The devil is in the details
ConsistencyTerminologyScreenshots
CompletenessIf your give code examples, make sure readers know what to do with themTest for dead links
03/25/09 Documentation: get it right! 32
Conclusion
Producing decent documentation is not rocket scienceIt just takes a lot of timeBut it's worth the effortHappy users -> AdoptionUser involvementHealthy community