View Full Version : documentation - do's and don'ts

20 Feb 2007, 9:12 AM
I'm about to begin developing a documentation system for a web application and I plan on using a style similar to Jack's, except primarily with added User Comments. However I was wanting to get some feedback from some people who have done this in the past.

I plan on having a tree system organization with complete documentation on functionality, not the code itself. This software is a MySQL database manager with built-in FTP, and a few other key components. We are going to have a section where users can implement their own custom modules and tools. That section will contain code documentation.

What are some good elements that make up good documentation? What should I avoid?

20 Feb 2007, 2:08 PM
I write doco every single day. As a developer, it helps me get things out of my head and into the doc. Users and applications' business owners love it. My clients love it because they feel comfortable that if I 'get hit by a bus' that they are not left at risk. Anyway, here's some personal, technology neutral input:

KISS. Keep it simple, stupid. Really...
Make it simple to contribute and edit. If it's more than one click it's too much.
Keep keeping it simple. Don't add features. The value is the content not the features. If you make it complex, authors (including you) will baulk and you'll end up with no content.
Have one taxonomy (tree), not more.
Make it simple to organise and reorganise the taxonomy. If you can easily reorg the tree you will do it - if it's difficult, your content and users will suffer. I have a one button 'Move' > 'Please select where you'd like to move the <pagetitle> page' and it moves the currently displayed node and all it's leaves. KISS.
Put all the styling, layout into 'the system' so that the author can do the minimum work for their content to look fantastic.
Don't provide features to allow the author to style their content so it looks disgusting.
Keep the content current.

I agree with you re layout. I love Jack's, Eclipse help style & MSDN style: left panel tree, right panel content.

Hope this helps...

20 Feb 2007, 8:40 PM
Those are some good tips, sometime in the next 48 hours I will begin the design for our documentation..... Thanks!