According to dictionary.com, Documentation is defined as : Computers. manuals, listings, diagrams, and other hard- or soft-copy written and graphic materials that describe the use, operation, maintenance, or design of software or hardware. Alas, If only this was the true "definition" of documentation.......
In my company, I inherited a project - lets call it FBB for FooBarBaz. My work is fun ( yes even at a megacorp, work can be fun!). It gets tedious and boring and interesting and I spend long hours @ work, but I am not complaining about that ( at least right now)! What I would like to talk about is documentation on FBB. Documents are required for maintenance of a project, right. So when I come on board, and am expected to 1. start developing 2. fix bugs 3. and support the Support Team AND there is just no docs to make my life simple, I get frustrated. I volunteer to start documentation in order to help me, the next person, the system administrator, and the Support Team. Wonderful: I know exactly what another Software Developer wants to see in a document, and since I am so smart, this shouldn't be a problem. Right?
Nope.....In order for me to write up a document which is actually useful, I have to speak to the people who were involved in FBB since day 1. -> Problems!! Either they are busy, or in another country, or simply not available. So a Software Engineer with very less background in FBB and the system gets stuck with writing all sorts of document, only 'coz she wanted to make life easy!
This is not just one "How does FBB work" document, There are Operations documents ( futile for me to write them up on so many levels ), Delivery Stuff, blah blah blah. I waste my time in doing "work" that really should be done by someone else. And of course, this is a ASAP requirement, BUT I need to focus on content as well as the darn formatting.
Don't get me wrong - I think we need documents in order to plan, develop and maintain a system. But the problem here is that either we don't have enough docs or we have way tooooo many with so much redundant information, that people just get turned off by documents and documentation. Vicious circle...
Subscribe to:
Post Comments (Atom)
7 comments:
It's a deep issue, yeah. One of those things that you really wish had been handled from the ground up instead of haphazardly accreting -- but when do you see software projects like that?
It's always so hard, coming on to a new project... how can we make making docs painless and awesome so things will be less black-magic-y in the future?
Certainly, the docs needs to be the right size with just enough useful information.
And once you make it, people will wonder how they lived without it.
Graham
Alex,
Yup its something like unit-testing that people in my company wake up to when the software has already been developed! I am trying my best here to document relevant and non-redundant information!
Graham,
Ha exactly! When I see the docs written up that I actually use, I refer to them continuously! The most useful document to me was the explanation of 3-word acronyms!
People should read this.
SiffVemoweami
[url=http://healthplusrx.com/nosebleed]nosebleed[/url]
PierWeest
golden goose sneakers
golden goose
yeezy
yeezy supply
supreme clothing
golden goose
goyard
supreme t shirt
adidas yeezy
golden goose
Post a Comment