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
