Questions?

You have questions, need to discuss documentation topics, or would like to suggest new features for projectdoc?

Quotes on Documentation

A word of warning...

Every document is a liability. Make sure that every document you write is worth its investment. Write sustainable documentation that document the why instead of the how. Do not head for perfection. Strive for automation and living documentation! This will make your documentation sustainable, fun and increase the return of invest.

Here are some quotes concerning documentation and writing that may be your guide:

Writing is hard work. A clear sentence is no accident. Very few sentences come out right the first time, or even the third time. Remember this as a consolation in moments of despair. If you find that writing is hard, it's because it is hard. It's one of the hardest things that people do.

Outside your extreme programming project, you will probably need documentation: by all means, write it. Inside your project, there is so much verbal communication that you may need very little else. Trust yourselves to know the difference.

If there is a business need for a document, the customer should request the document in the same way that she would request a feature: with a story card. The team will estimate the cost of the document, and the customer may schedule it in any iteration she wishes.

XP is designed to use face to face human communication in place of written documentation wherever possible. Effective conversation is faster and more effective than written documentation. When you bring people together, they need less paperwork.

MindTouch, for example, argues that documentation represents potential profit, rather than a cost, because it's not a finely crafted mess of marketing jargon — documentation is legitimately useful from a developer's perspective. As such, it can help you build and sustain communities!