In my last job it was deemed light-years ahead of industry practice for the documenters to actually work in the same office as the developers. Instead of getting to see the product 2 weeks before shipment, why!... they had a whole month to ask the developers themselves what it was supposed to do. To have it demonstrated, and to struggle to communicate these arcana to other coders who thought the same way as the coders they'd had to milk for the knowledge. Which wasn't at all how they thought themselves.
In practice the place was so status-ridden the documenters had to purify themselves with smudge before they'd dare approach one of the heaven-born. I once took a documenter aside to explain to her about my contribution: she cried rapo to her boss as a result. Look, I said -- it's a weird facility and it only has the form it does to enable Excel's Replicate to work. No other reason. Somehow you must communicate this to your readership or else the whole thing is going to look like it's from Mars, if not from Hell. But no: I was trying to tell her her job. A cardinal sin, in a country where you can be fired with no redress if someone else can do your job. So the product got shipped with her confused write-up, and I got a name for being a mischievous masher. I returned from Planet USA with a huge sigh of relief. But things aren't perfect here either... So the documentation doesn't quite explain what the product actually does? Well, you could knock me down with a feather. Ian 2010/3/13 Björn Helgason <[email protected]>: > I have seen it so many times that documentation is way off what the > actual code does. > > I find it quite funny going to presentations about systems and the > salespeople are usually saying. > > "Now the systems are doing what we told you they were doing last year. > Last years systems had a lot of bugs and did not do what we said it > did but now it does" > > I remember sometimes in the past pointing at something in a > documentation and asking why the system was not doing what it said in > the documentation and the best results I got when the next review of > the document arrived the functionality had been removed from the > documentation. > > In a way it is actually better that the documentation tells you what > the system actually does rather than some wishful thinking of what it > might do once the bugs are out. > > 2010/3/12 Don Guinn <[email protected]>: >> Since I code as a hobby now, I might start something then put it down for >> days or weeks. So I document as I code so I have some chance to understand >> what I was trying to do as opposed to what I actually did. >> >> 2010/3/12 Björn Helgason <[email protected]> >> >>> When you decide to create a system you are supposed to write specs and >>> then create documentation and then write the code or is it the other >>> way around? >>> >>> It is interesting to not that applications and documentation is >>> somewhat similar to quality systems. >>> >>> Very many companies struggle to implement quality system by first >>> writing a quality guide book and then try to let the company work like >>> the quality book says and advertise that the company follows standard >>> so and so. >>> >>> My experince is that you are much better off looking how a company >>> operates document that and then you have a quality documentation. >>> >>> Similar with applications then it is most often so that systems happen >>> and then you write the documentation afterwards. >>> >>> It is especially true with system written in languages like J and other >>> APLs. >>> >>> You sit down with a potential customer and drift a system with the >>> customer and write the code more or less on the spot with the >>> customer. >>> >>> That is why those kind of systems are done very quickly and the >>> customer likes it. >>> >>> Then comes time to write the documentation but very often there is not >>> very much effort put into the documentation. >>> >>> Then again sometimes there is documentation written but there will be >>> changes made to the system and then they need to be documented. >>> >>> Most of the time the documentation is thus wrong. >>> >>> If you try to do it the other way around and write specs and >>> documentation first it is very often worse outcome. >>> >>> So what do we do? >>> >>> At least not print any documentation and try to create online >>> documentation and keep it as close as possible to the code. >>> >>> -- >>> Björn Helgason, Verkfræðingur >>> Fornustekkum II >>> 781 Hornafirði, >>> t-póst: [email protected] >>> gsm: +3546985532 >>> sími: +3544781286 >>> http://groups.google.com/group/J-Programming >>> >>> >>> Tæknikunnátta höndlar hið flókna, sköpunargáfa er meistari einfaldleikans >>> >>> góður kennari getur stigið á tær án þess að glansinn fari af skónum >>> /|_ .-----------------------------------. >>> ,' .\ / | Með léttri lund verður | >>> ,--' _,' | Dagurinn í dag | >>> / / | Enn betri en gærdagurinn | >>> ( -. | `-----------------------------------' >>> | ) | (\_ _/) >>> (`-. '--.) (='.'=) ♖♘♗♕♔♙ >>> `. )----' (")_(") ☃☠ >>> ---------------------------------------------------------------------- >>> For information about J forums see http://www.jsoftware.com/forums.htm >> ---------------------------------------------------------------------- >> For information about J forums see http://www.jsoftware.com/forums.htm > > > > -- > Björn Helgason, Verkfræðingur > Fornustekkum II > 781 Hornafirði, > t-póst: [email protected] > gsm: +3546985532 > sími: +3544781286 > http://groups.google.com/group/J-Programming > > > Tæknikunnátta höndlar hið flókna, sköpunargáfa er meistari einfaldleikans > > góður kennari getur stigið á tær án þess að glansinn fari af skónum > /|_ .-----------------------------------. > ,' .\ / | Með léttri lund verður | > ,--' _,' | Dagurinn í dag | > / / | Enn betri en gærdagurinn | > ( -. | `-----------------------------------' > | ) | (\_ _/) > (`-. '--.) (='.'=) ♖♘♗♕♔♙ > `. )----' (")_(") ☃☠ > ---------------------------------------------------------------------- > For information about J forums see http://www.jsoftware.com/forums.htm ---------------------------------------------------------------------- For information about J forums see http://www.jsoftware.com/forums.htm
