The documentation is mostly for myself as seldom to others see my code. I update it as I code trying to keep them in some sort of synch. J is so terse that I use the time updating the documentation to think about what I'm doing. When I wrote in Basic or Fortran there was lots more busy work in the coding giving me more time to think about the problem. In J I might fumble around for an hour writing one line of code. A bit of explanation is quite helpful when I look at it again in six months or so. I haven't mastered reading J as well as I would like.
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
