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/

Documentation Consultants

[zpengo]

Hire a massively-qualified technical writer to serve as a consultant in order to help get things in order. They can start establishing conventions, getting a team of writers together, determining your current and future documetation needs, and figuring out how to resolve those needs.

Far too many companies approach tech writing as the "music department" of the company: Nice to have, but not really necessary. The problem is that the lack of attention given to quality documentation winds up costing the company later. If you don't know where to find such a consultant, you could always shoot off an e-mail to a highly qualified individual such as myself. *smirk*

Documenation is not your only problem...

[soap.xml]

From the what you said with different people and different or no methodologies there is a lot that needs to be done. First off, standards:

• Literate Programing: What you write, should make sence. Variables such as a, b, c, thing, object, stuff, crap etc should not be allowed. A new programmer should be able to come into your shop, read the code and it should make sense.
• Commenting: All source should be commented. That doesn't mean that hlaf your source files should be comments, but anything that doesns't make sense by simply reading the code needs to be commented. At a bare minimum, the person who wrote the code should have there name in there ;)
• Source Control: Please tell me you have CVS or something like that setup. If not, set it up
• Testing: Test early and test often. When your done with that, test again. ;) You might want to investigate Extreme Programming. This will help quite a bit to launch good solid projects, on time.
• Standard Design Methods: It will help you out quite a bit to have standard design methodologies. Standard patterns to follow and ways of doing things will help you quite a bit.

Secondly, make sure you have a forum for you developers to work together. Setup an IRC channel or something, just make sure you have a place to chat and share experiances / bugs ;)

Those few things should get you started. They don't totally address the commenting issues, but I would say that is the least of your problems... I could be reading way to much between the lines. Just my two cents.

-ryan

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!

Re:WIKI

[RickySilk]

We started using a wiki about a month ago and we love it! We named it "The Brain" and it "keeps getting smarter". Highly recommended.

Since you seem to be a cold fusion shop, try this out http://www.cdsi-solutions.com/cfwiki/ we had it running in about 2 minutes.