Earlier this year I spoke at CampKDE in San Diego, CA talking about Documentation. At the time there was a question asked about my thoughts on the roles of wiki pages and documentation. This has been on my mind for the last couple months and with the re-write of the Kubuntu Docs for the April release of 10.04 “Lucid Lynx” I have been thinking of the best way to get all the resources to work together within the world of documentation.
You can break documentation down into three basic categories; System Documentation, Distro Documentation and Wiki Documentation.
With these three you should be able to cover what is needed and required for good quality documentation. The key to all of this is flawless integration flowing down to the user. All three parts should be able to work together and refer to each other if needed.
System Documentation
This documentation is from the Desktop Environment. It should include documentation on the core packages, the environment and included installed programs.
Distro Documentation
This should include any distro specific changes from the environment, any programs install from the distro and any design changes.
Wiki Documentation
This is for setting up more detail. This should hold the key for setting up hardware along with tips and tricks. This is where you go into more detail.
Writing System and Distro Documentation
When writing documentation there are a few things you want to keep in mind.
Keep it simple. If you can explain the purpose or the use of something in 10 lines vice 50. Do it that way. Most people give up if they don’t see a resemblance of help in a quick scan.
Use prerequisites. If you are documenting the use of a network manager, prior them setting it up make sure you state they have connection. If not find a place in wiki documentation that explains in detail how to setup network hardware so the user will not get frustrated.
Overall system and distro documentation should be as non-technical as possible. This is for explaining the purpose and use of what you are documenting.
When writing documentation don’t shy away from the use of comments. This will help anyone coming behind you in trying to fix something find what they are looking for. Documentation inside is documentation is very important.
Wiki Documentation
There has been a fight for some time from the documentors and the wiki maintainers who is right. With this model both are given very hard and important tasks. This is where you can get in depth with explaining how to setup and use your system. This should be maintained by the distro itself for distro specific help. This is where you talk about setting up and use of the distro. Tweaking things to get each system working. This goes hand in hand with IRC help and Forums. The forums and irc are centers where people who get stuck in the wiki should be able to go when they need help with their system.
Overall documentation on every level is just as important as the last. With this model, it is impactive that all parties work together to ensure that references back and forth are smooth and seamless.
Just remember, we are here for the end user.
Tags: document, documentation, Kubuntu, Linux
I just found this blog a while back when a friend recommended it to me. I’ve been a regular reader ever since.