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 always liked the record keeping as done in the biotech area... Every scientist has a lab notebook (offline) where references are made to everything that was done (and where things can be found).
:)
I'm always suspect of documentation and record keeping that is 100% digital. If the notebooks are witnessed and microfilmed, there will never be a question on when the work was done.
If notes about how things are done are kept on a notebook like that, it is a lot easier to go back and figure out what was done and how it was implemented when it comes time to writing real documentation. This does not address the inprogress documentation, but you should not forget about the tracking aspects. (CVS is good, but it could be falsified easier than a notebook I would think).
Don't get me wrong, I hate doing this... but it is a good idea
DrArt
-- Huh?
are you documenting for users of the projects or are you documenting for present and future developers of the project? The two are completely different and have different requirements as such.
A web application by nature should almost always be self explanatory. A help link or button should be available prominently on every page. The better you do this part, the less it costs to support your app.
Developer documentation for a web app also works well with HTML. Not only can you use comments extensively, you can link variables and functions from where they are used to their actual definition. A common way to structure HTML documentation is to have a frame with the left frame containing a tree of links, an index, and a search. I would use something like ht://dig rather than a database to index your docs and allow searches.
No, Thursday's out. How about never - is never good for you?
Or, if you want to use PHP, try PHPwiki, at http://phpwiki.sourceforge.net/
I'd give a working example of a wiki, but I'm worried about the Slashdot effect on it -- the guy might run up bandwidth costs (and he's not my enemy), and it might become too popular (which means too expensive to run, and it means that it would be edited too quickly and by too many people so that it would lose its small-community feel that Slashdot has also lost).
Maybe you mean something different here, but Literate Programming is a field, invented by Donald Knuth, that has little to do with what you are saying here.
There are many good reference, try this one, for example.
AFAICT, the tradition of Literate Programming comes out of Mathematics where proofs are given as narrative, but the equations (programs by analogy) are terse.
For example, this example, written by Knuth himself, contains many example of terse variable names like rx, h, t, l, etc.
Read The Mythical Man-Month by Frederick P. Brooks, Jr. (ISBN 0-201-83595-9). This is one of the best books I've ever read when it comes to managing any sort of software product - and it gives great advice, including a chapter on documentation and why it is so IMPORTANT.
Please, go out and buy it and read it - or check it out from your local library. It is a must for all programmers, even if you're not the one in charge.
Jake
Dating: while( 1 ){ call_girl(); get_rejected(); drink_40(); } return 0;