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
The primer gray Raleigh sky cheers the regulars within the alley behind Bob's Free Software Café, but not enough to draw them beyond the confines of their narrow world. The pecking order is clear as occasionally one of those nearest the steel drums, each containing a low fire, barks out a command to "pass up another bible", 'bible' being slang for the Linux books lying in tarp covered piles along the sides of the alley. On arrival, the bible is torn asunder and carefully fed into the perpetual fire. Fingerless old gloves type on invisible keyboards as the small knots of aimless alley residents talk to one another, forever modifying their favorite section of code. Laptops were once common but have long since passed through the local Open Source Pawn Shop to become just another fondly recalled and often mentioned memory for it's former owner.
The mumbling and air keyboarding is abruptly halted by a large steel door being thrust open, the doorframe filled by a huge biker entrusted with access control for the café. "Listen up", he cries, "send me in four guys with Wine experience, two with boot loader experience, and one of you stinkin' weenies with Gnome experience. And get a move on it." All heads at once turn towards the centermost steel drum.
One man speaks quietly, so quietly that even those who stand beside him must lean towards him to hear. Assignments are being given out. People will move into the café' based on this man's decision, new code will be added to the sacred scroll, new reputations could be made or old ones broken depending on what happens within the café, and only Linus can decide who enters the café'. Linus has retained his laptop, he's even managed to retain sufficient funds to live at the Y and ride the bus down to the alley each morning. Not everyone has fared so well. Most struggle to hold onto a good packing crate or drainage pipe for their home, much less ride a bus. Those who still retain a skateboard for their transport are considered wealthy, as are those who still own a backpack. All are former shareholders in Red Hat or other Linux companies, and all were faithful to the end, going down with their choice of Linux ships. The faithful had not so much as batted an eye the captains from the assorted Linux liners were rowed to waiting yachts by their faithful executives. Now, the faithful share their faith here in the alley and eschew opportunities outside of Linux as a tenant of the faith.
Linus decides, the word is passed through the crowd that the seven slots will be filled by six old timers and one "egg", a new guy no one knows much about. The old timers are near the door and line up, but the egg has to "pardon me" and "excuse me" his way through the mass of huddled hopefuls as he moves towards the door. It's some guy who once owned a whole ton of stock in Red Hat, something that's not supposed to make any difference. In his wake there's a lot of disgruntled chatter and an occasional complaint voiced loud enough to hear above the general murmur. "Hey, what's with the egg moving up so soon", someone finally shouts. Linus, obviously shocked as the challenge to his authority, slowly turns in the direction of the question. "You people know I make my decisions based on skills and skills alone. You all read the code. You all review it. You can see for yourself that this egg has made an important contribution. I don't like this type of insinuation and I don't expect to hear it again". He then turns back to the steel drum, bends over, and removes his laptop from his backpack. There will be no more comment from the crowd, Linus is coding, no one dares to interrupt Linus when he's coding.
By now, the egg has finally reached the doorway and falls in line behind the old-timers, the line is then allowed to pass through the doorway, the door promptly slammed behind the egg and a loud clack is heard as it's locked.
The café' interior is a stark contrast to the alley, something straight out of an old episode of "Miami Vice". The raised platform in the center is populated by several dozen obviously well heeled folk sitting before expensive flat panel displays, drinking gourmet coffee (the alley residents can still recognize that wonderful smell), snacking, and occasionally laughing, lost in the conversations piped into their hands free headsets, totally unconcerned with the grubby batch of Penguinistas who have just been shuffled in through the back door. Penguinistas called these people specialists, and specialists spent their time looking for arrangements and deals that made the PR people happy, the PR people being happiest when the deals resulted in PR adequate to sell shares of stock in the Café. At the rear of the café' are a half dozen old 386 machines with filthy keyboards and faltering monitors, all sitting on what appears to be countertop ripped out of an old kitchen somewhere. As a smiling guy with a Red Hat ball cap approaches, the mumbled name "Bob Young" passes down the disheveled line.
"I'm awfully glad to see you guys and would love to chat, but we need to hurry right along guys, OK?" as if anyone in the line would dare challenge Young on anything. "Now, you old-timers can each move over to a terminal, I'm sure you can look at what's on the screen and know which one you need to work at. You all know the code, right? Sure you do, so you'll know what section is your specialty and know what to work on. We'll have some Maxwell House sent right over, but remember, only one cup each". Young then turns to the egg, his grin gone, replaced by an almost bland stare. "Follow me", Young commanded before spinning on his heel and heading rapidly across the café. The egg follows young across the café to a steel door almost identical to the one he's entered through.
"OK, kid", Young said while unlocking a gray steel cabinet next to the door, "Linus says you're trustworthy, and you damn well better be". Withdrawing an envelope from the cabinet then quickly closing and locking it, he continued, "you take this CD over to the Y, the guy at the desk knows what to do, there's no need for you to open your mouth. Just hand it to him, wait until he hands you back an envelope, and then come straight back here. Knock three times on this door, then wait". The egg nodded, confused a bit by his assignment, wondering what was the goal, but then slapped back to reality as Young noticed his change of expression, with "don't fuck this up, egg. You do it right and you can do down the hall there on my right. Go ahead, look down the hallway to my right". The egg already had, he'd seen the lavish office chair sitting before a large flat panel display and already wondered what it was and why it was separated from everything else. "See it, don't you?" Young barked.
"Sure, I mean, yes sir Mr. Young, I see it", stammered the egg. "Well", replied Young, "if everything is kosher when you bring back the envelope, you haven't opened it, you get your ass right back here in a hurry and keep your mouth shut along the way, you can go down the hallway and fire up that new machine. It's got XP on it, any game you want, and the very best audio and video. You'll get three hours in there, just you, the machine, and your favorite game. No hassles, a full coffee pot, even a pack of smokes if you want them. Everything clear?" Yes, yes, it was all clear. He was going to get his fondest desire, a chance to play "Monster Truck Rally" years before it would ever be ported to Linux. God, could it ever get better than this.
"Wipe that stupid grin off your face, egg", whispered Young, "you want someone to notice you're thinking about something other than writing code for Linux? Now, I'll open the door and you hustle your ass off, egg, otherwise you're back out in the alley and just another egg fit only to pass out copies or Red Hat Linux in hopes of getting other eggs hooked". The egg fairly flew out the door, visions of Monster Truck Rally glowing in his head. He'd seen it on the Xbox, heard it had been put on the PC as well, but never actually tried it. Someone might have seen him in front of the Xbox at Wal-Mart where the game ran constantly for customers to try out, he'd never risk that. But now, a chance to actually play the game, this was even better than getting a chance to add to the code base. This was a chance to actually USE a computer just as if the main purpose of a computer was to let the user do what he wanted. You better believe he'd come straight back, he'd be back before Young could get the door locked if that was possible, thought the egg.
He tried to put all thought of the CD he was carrying out of his mind. He'd heard the lies about the Y running Windows, now he wasn't so sure they were lies. He wasn't sure at all in fact since inked on the outside of the envelope in bold letters was "MS W2k Corp Serv. Product Key" followed by a series of numbers. "At least", he thought, "Linux is still growing in the third world. Once it gets a solid base there, once the new versions and new drivers are all built, then it can come back stronger than ever. So what if a compromise is made here and there along the way in order to keep a prospective customer happy. It's not like someone is actually buying a legal copy of this Microsoft shit, it's more like keeping the money out of the hands of the evil empire any way you can. Young knows what he'd doing, he'll make a go of the Café then start that support thing back up". And with that, he ran on, focused only on getting back to the Café and firing up Rally.
Ok, I've been drinking Stella Artois and smoking green all night but why the fuck is this parent set to +5 Funny?
Invoicing, Time Tracking, Reporting
Come on editors - why rated as funny?
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.)
There appear to be a few rogue moderators who assign +1 Funny to highly rated posts. They think it's funny.
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....
1) Create incredibly complex database systems and the applications associated with it.
:-)
2) Hire a bunch of bright interns at 10 bucks an hour to figure out how the system works.
3) Make the interns write extensive documentation.
4) Write whatever the hell the interns want on their evaluation reports.
5) A win-win situation for all.
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!