> Well, I seem to have stirred up some communication here. > Good for me :) > > Of course I overstated my position and I did it to spur the dialog. > > Documentation is very important. But it is a management > responsibility and management must be prepared to foot the > bill or suffer the consequences.
The smartest corp. approach I've seen was years ago, with Royal Insurance (downtown NYC at the time), where they had a (likeable and skilled) tech writer who handled published doc. He would schedule some time to sit and talk about the work being documented, go write it up, and then come back again to make sure it was right, repeating as necessary. Worked real good, and he was able to handle a group of maybe 30 people. > Project specs are certainly important. You wouldn't build a > house without some kind of plan in mind and if you are going > to get help doing it, that plan has to be on paper in a > precise manner, lest there be misunderstandings. > > What I wrote was really aimed toward repair or enhancement of > existing work. The first time the documentation lies is > usually the last time you trust it. Unless you're the author, then it's "oh, I didn't finish that" <s> > Over the years I've seen the gamut of situations. There are > two that stick out: One was a project where documentation > was never mentioned until it was time for the client to pay. > He used the lack of doc as a reason for not paying. The > other was the project manager who would insist on looking > over your shoulder and making sure that EVERY line of > Assembler code was documented, even at the earliest stages of > coding. Of course that led to this kind of documentation: > > L A5,Name : Put Name in Register A5 > > Which I suppose is good for learning assembler. I worked > with one person who claimed to know assembler. She would > write the program in Fortran and get a machine code > pseudo-assembler listing. Then she would hand-code a new > symbolic and pass it through the assembler. That's pretty weird. I'm an old assembler hand myself, btw. > Documentation, like testing, is too important to be left to > the development staff. I guess I have to agree, but small (as in very, very, very small) shops have to work harder, if not smarter. What I do is keep a Robohelp doc window open while writing/testing code, and then - it does take effort - to end the session with updating the doc. I admit, it is hard, though, because after a long session and being tired, it takes a big effort to start again, in a sense, with the doc, but that's the best time to do it, when it's still fresh in mind. There is also a level of satisfaction/reward when the doc looks good and makes sense. Another added value is that writing the user/developer doc can bring out problems or omissions in the code that weren't seen at the time. True, large companies (especially insurance!) don't have to work this hard, but I'm talking small. Did I say small? I mean really small, like I could carpet the whole company with a few postage stamps :) Bill > HALinNY _______________________________________________ Post Messages to: [email protected] Subscription Maintenance: http://leafe.com/mailman/listinfo/profox OT-free version of this list: http://leafe.com/mailman/listinfo/profoxtech ** All postings, unless explicitly stated otherwise, are the opinions of the author, and do not constitute legal or medical advice. This statement is added to the messages for those lawyers who are too stupid to see the obvious.
