Beginning Project Documentation?

mirthe_v writes "Hi, I'm working for a small webcompany (about 20 people), with ColdFusion programmers and designing staff. We all work on a bunch of projects (Internet, intranet, cd-roms, etc.) on the same time, with different people and different or no methodologies. There is an ever growing need for documentation, but we have no idea where to start."

mirthe_v continues: "I was just wondering how other people/companies keep track of their current and older projects.
Do you put stuff in a database, if so, what about all those diagrams and handwritten notes.
If not, do you store things in a folder per project, and how do you then stop documentation from getting lost and making sure people store things where they should.

"As I said, I don't know where to start, especially since the staff varies greatly in the need for documentation, technical background, experience with writing documentation and even different languages (English and Dutch).

"Please share all your thoughts and experiences. Cheers, Mirthe""

Comments

KDE

[EricKrout.com]

I know that the KDE team uses DocBook,
for which there's a great guide (crash course)
that they encourage their writers to use.

m o n o l i n u x :: All Day Long. All Day Strong.

http://twiki.org/

[freebsd45]

TWiki, a flexible, powerful, and easy to use Web-based collaboration platform has worked well for us.

http://twiki.org/

A simple system that we use

[humblecoder]

Here is a simple system that might work for you:

1. Code level documentation. Having good code-level comments is vey important for figuring out the nuts and bolts of how things work. Well commented and well structured code can make or break a long term project. The important thing is to keep the comments up to date so that you aren't providing misleading information. This is easy to do, however. All it takes is a little dicipline.

2. Process and Design Documents. There are many ways to handle these, but one simple way to do it is to create a development "Intranet" and keep all of your developer docs in HTML format. HTML documents are easy to create, easy to organize with hyperlinks, and easy to view. Keep a copy of your HTML documents in CVS or some other version control tool. That way you can have a record of your changes.

Code level docs are pretty easy to get started. If you have a good development team, you probably already have your code well organized. If not, assign pieces of your project to different programmers and have them document their assigned code.

Design and Process docs can be handled the same way. Make a list of things that you need to document (ex: build instructions, class hierarchies, etc) and assign these out to programmers.

The key to any documentation system is to keep things up to date. The best protocol is to have people make changes to the docs as they change the system, or as they discover bugs in the docs. Treat your docs just like you would source code. Strive for "bug free" docs. If you can't make a change to a document for whatever reason, log it as a bug so the change doesn't fall through the cracks.

Once people get used to treating docs as code, they will keep them up to date. If people have the attitude of "I'll document it when I have the chance" your system is doomed to fail.

Good luck!