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""
Hire a new guy/girl...it's easier to saddle the new guy/girl with the crappy (but very important) jobs!
-Ben
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...
:)
microsoftword.mp3 - it doesn't care that they're not words...
Documentation is like sex: when it is good, it is very, very good; and when it is bad, it is better than nothing.
But I like less better than more (at least when using Solaris ;-)
Assign each person to use a different word processor - e.g. Word95, Word97, Word2000, WP5.1, StarOffice, OpenOffice, etc.etc.
:(
This way you will know exactly who maintains the document - store all the files on the users hard drive , dont worry about backups - hard drives are very, very reliable these days and the damn server is usually always on the blink.
If someone needs to modify another document, they simply need to write notes on the old printed version and the document maintainer can update them later.
At least that's how it was in my last job
I'll think of a funny sig later on
Its a self defining gag. The funny thing is that it is rated as funny, when it's not, and you guys are freaking out about it.
(yeah, its a stretch, I know.)
Every single web based document management system I've ever seen has been a complete pain in the ass. As a consultant I've seen 3 or 4 at various client sites. No one ever knows how to use it right, it is always klunky and it mostly gets ignored.
What is important with whatever documentation you keep is that you have it easily available for everyone. Everyone also needs to be able to easily get the most current copy and be able to submit new information into the current copy.
Sound like version control to anyone? Yup, just use whatever version control software you have on your project. Something that the developers already know how to use. Put the docs under the same project as the source code. When I cvs update (or whatever) to get the current code, I should also get the current doc.
Using CVS will not be the most efficient if you are using Word for your docs, since you have to store the whole binary each time. This isn't usually a problem, but the storage can get big quick. Also you won't get what changed each time since it is a binary. Text files clears this up.
Getting your business guys to use CVS is another whole can of worms, but at least all the developers can get the docs easily.
My documentation lives in a vacuum. My tech manuals live in a Hoover, and my user manuals live in a Sears Craftsman Shop Vac. I guess you could say my documentation system sucks
Thank you, I'll be here all week.
XML causes global warming.
TWiki, a flexible, powerful, and easy to use Web-based collaboration platform...
Does it have an audible announcement for notifications? Maybe something along the lines of, "BeeDeeBeeDeeBeeDee. Hey, Buck!"
--
"Outlook not so good." That magic 8-ball knows everything! I'll ask about Exchange Server next.
we have no idea where to start.
"The "
I am anarch of all I survey.
Patrick Doyle
I mod down every jackass who puts his moderation policy in his sig. Oh, wait a sec....
Hey can you imagine a Beowulf of these?
(He runneth for cover)
I say the future is a serious matter
And so for god's sake - hock and soda water!