Slashdot Mirror
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""
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.
This sig has been temporarily disconnected or is no longer in service
In fact this doxygen was only part of the solution, our research projects had other documentation which required addition, however we simply had the developers get into using LyX and had the doxygen script merge in the static docs with the code documentation. Made for a nice doc tree which was easy to update (and if you really want to get fancy every once in a while, import into LyX and whip up a tasty DocBook). Of course the developers has to conform to the commenting style required, however if this is a problem for your development team, then the whole 'team' concept isn't going so well.
If you don't use CVS and/or doxygen, and those tools don't fit into your workplace (although CVS should be used, IMHO). You could easily whip up a php or perl script to merge TODO and Changelog files, this is of course assuming that all the developers use these files to track their work, which they should do anyhow (at least in some form). It would be trivial to whip up a parser in perl and merge those files into some sort of report. Thus the whole Practical Extraction and Reporting Lanuage thing...
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.
Do you have one of those obnoxious newbies programmers who fancies himself a total hax0r, creating variable names like "it3r80R" when a simple "i" would do, or putting hundreds of little in-jokes and wisecracks throughout the comments? If so, he's got to cut that shit out.
In my experience, peer review is more important here than methodology. In fact, methodology can afford to be rather sparse (and it should be for most circumstances) when peer review is relied upon.
Peer review is good because it helps good programmers become better programmers and at the same time, stops bad programmers from doing really stupid things. I think documentation is something that should be done, for the most part, after a project is close to completion.
For instance, we followed the standard procedure of design, then implementation, etc., etc.. Problem was that the people who did the design and implementation, weren't a part of the maintenience phase and all that design stuff was no where near how things were actually implemented.
It's really something that can't be avoided. Code tends to have a mind of it's own once it's written. There's a bit of a chaotic factor in it to where the slightest unforeseen bug in the most obscure case senario leads into a huge design problem.
Besides, it's alot easier to manage with a working product with poor documentation that it is to manage with a broken product, and acceptable documentation (or even good for that matter).
int func(int a);
func((b += 3, b));
Whatever you do, don't write any documents at this time. Instead put everyone (if possible) in one big room, with pens and whiteboards along all the walls. Supply lots of coffee, food, snacks and soft drinks.
Let them hash out all the details of what you believe the customer wants. If you have a real customer available, chain him to a table in that room and don't let him go until you're satisfied.
Write down user stories on post-it notes, stick them to the walls, sketch UI designs and user interactions on the whiteboards. Don't worry about documentation! What matters is that you all have the same vision and understanding of what to do.
Documentation on paper is just about the worst medium possible for transferring information from one person to another. It is one way, it is low bandwidth, it is not visual (unless you have lots of pictures and such). It basically sucks. Two or more persons by a whiteboard is the best possible technology for information transafer. The ultimate solution is if you have a printing whiteboard, which can give you a hard copy of what you just jotted down.
The real documentation, on paper or on the web, can come much later, when things have stabilized a bit. In the end it may never be needed, in case your project is cancelled.
All these tips comes straight from the book Agile Software Development, by Alistair Cockburn. The best SW related book I've read in years!
Mats