Style Guide

Writing

Write the kind of documentation that you would like to read. Our role models are old Unix man pages and the MySQL online HTML pages (with user comments!). Our anti-role-models are Windows help pages: "To start a new file, choose File -> New".

Know your audience. Be chatty and explain concepts in a tutorial page. In a reference page be above all precise, then concise, and finally if possible be interesting to read (but this is a distant third). For every setting where it makes sense (and it almost always does) be crystal clear about what the default is. Offer guidance on what the best practices are and why.

Be honest about limits, shortcomings, misbehavior and the like. When it makes sense, document internal things (include a disclaimer that this is something internal, and if you count on it not changing you'll probably be surprised.) We have no secrets to hide, we have no marketing department to keep happy.

Read more than you write. While warming up to bang out a new section of the manual, proofread a page and look for ways the code has changed from when the page was written. You should almost always find yourself reading code in order to write the docs about it. For some of this code, writing the documentation on it is the closest to careful QA it will ever get. Don't pass up this chance to kill a few bugs.

HTML Stuff

Copyright

Your contributions to the manual are on the same terms as the rest of the project. Read the license and decide if you can accept it before submitting documentation.