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/

Re:http://twiki.org/

[p3d0]

it would lose its small-community feel that Slashdot has also lost

You mean back in the good old days when you first joined, when it was only you and the 264,599 other users?

Document repositories...

[sterno]

I've found that CVS works well as a document repository. Any sort of version control system is well suited to the task of keeping documents. The only trick beyond that is establishing an organizational structure for it.

As far as organizational structure, base it on the development process you use. So in each phase of development, you have the documents needed for that phase seperate from everything else. If you have deliverable documents, put those in a directory and then have subdirectories for any supporting material.

That's a suggestion. I would highly recommend sitting down and formally structuring this. If everybody knows where the documents are, and where to put new documents as they generate them you'll have a lot easier time of things.

Re:Start like writing started: Oral Tradition

[abe ferlman]

I say keep the oral tradition. Hire a master storyteller and have this person write lays and epics about the overwhelming odds and unimaginable challenges your programmers faced, and the way that these struggles between good and evil shaped the interface you see today.

Who wouldn't buy the support contract if it included a yearly visit from the master storyteller? By jove I believe I've just solved the "how to make money from GPL softare" problem...

:)

You mentioned Cold Fusion

[DeltaOne18]

Since you use Cold Fusion I would recommend checking out FuseBox is a web application methology develop orginally with Cold Fusion but now applicable to all the major web app languages (PHP, Java, ASP, ect).

Part of FuseBox is FuseDoc which is a XML based spec for putting docuementation inside your CF code. By using Fusebox and FuseDoc you can break your web apps out into separate modules that work together much like different objects in C++ or Java. This allows you to have multiple people working on an app at the same time, while also separating your content from programming logic. I have used this approach in several web apps and it has worked well. Couple these techniques with something like CVS and some organizational programming standards (make standards that make sense!) you should be able to improve your work enviroment.

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!