documentation heaven

[crystalized]

Well I am on my last day at my current job and finishing up on some of the documentation, honing the comments in my code, updating changes etc.

Early on in the project I was doing code documentation very regularly (formally documenting it in a maintenance manual). Then I found that I had to make some major revisions in the code due to some changes in requirements. So after I had spent hours documenting the code I had to rewrite the code and redocument. As much fun as this was I found that it reduced my urge to document promptly. I still comment my code (maybe a little too much) but the formal documentation took a little longer.

What importance do people place on formal documentation, that is seperate from the code. If you come into a job where you have to work on something someone else made, do you even look at the formal documentation? Or do you only refer to it if you do not understand something that is being done in the code?
Crystal
crystalized_s@yahoo.com

--------------------------------------------------

Experience is one thing you can't get for nothing.

-Oscar Wilde

 

[Karl Blessing]

well that depends on how many companies actually have formal documenttation, usally formal documention is good to get an idea of the product, but the comments inside of the code can actually help much more, although it depeneds how your formal documentation is laid out, We have a project that is 4 years old now, I would say least 50 people have worked on the project (not all together, but going through the hands of about 50 people) most of the site does not have comments within the code, but rather comments at the top dated when the change was made, by who, and a brief memo.

But to say the least any new people comming in and was expected to work on this project (I being one of them, except I've been here for a little over a year now, the other two new guys not more than a couple months) we all agree that the project is quite unruly. Since the project does work, its just so wound together, so many different things to take care of, not standardized, every page is both independant and dependant, that a change may or may not affect other sections. It is the weakness of entry programmer, lazy contractor, programmers who dont comment, and managment who dont want codes cluttered with comments, and so forth.

so from my own experience, internal comments in the code is ALWAYS a plus, there are still some parts of the site I still dont understand, such as the second activeX dll we use, that is supposed to be our DB connection, while the other dlls do the querying, basically we're working more on cosmetics for the ESC, than we are with the data.
Karl
kb244@kb244.com

http://www.kb244.com

Experienced in : C++(both VC++ and Borland),VB1(dos) thru VB6, Delphi 3 pro, HTML, Visual InterDev 6(ASP(WebProgramming/Vbscript)

http://www.brainbench.com/transcript.jsp?pid=629151

 

[rbfowler]

I worked as an EDP auditor for awhile, and have seen the blessings of good documentation and the curse of bad documentation. Documentation for an application will indicate what each module should do, what inputs and outputs are expected, what error trapping routines should be in place, etc. Internal comments for command changes within a subroutine are good, but won't help when the program goes haywire for "no apparent reason". We have chased a problem through literally thousands of lines of code for a poorly documented application, because no one could figure out what each module should have been doing. I hate doing it too, but it's a lot easier getting it done up front when there's no pressure. If its just an applet, no big deal. But for a major app, documentation needs to be there.

 

[CitrixEngineer]

Not just for application development, but for systems administration, too.

I've visited sites with 250+ servers, many built by different people to different standards and specifications - different options installed, that sort of thing.

I tend to concentrate on the Metaframe servers, fairly obviously, but if, for example, there is no documentation on the way the network has been setup, services on various other servers, etc, the entire MetaFrame setup can be a minefield.

Also, there is nothing more annoying than wasting a hour or so hunting for the correct drivers so that a server can be rebuilt.

Good systems administrators document every server and keep supporting software in a dedicated file to that server. Yes, that means cupboards full of files. And easy to manage systems. This = low support costs - who wants to pay a £75 hourly rate for a guy to download drivers from the internet?

 

[crystalized]

I know I just left a place where the network has exactly no documentation whatsoever. Thank goodness I was not the net admin there. I can only imagine what will happen when someday they need a full time admin who will have to figure out everything that is going on there from scratch. Eeeeeek!
Crystal
crystalized_s@yahoo.com

--------------------------------------------------

Experience is one thing you can't get for nothing.

-Oscar Wilde

 

[Karl Blessing]

kind of the same here, except we only have 2 servers, and about 8 PCs, of which I have to take care of( I also do their programming , office maintenence, well you get the point) but we dont have documentation on it. Thats more than I can say about the ESC (Employment Security Commision) of NC, they have maybe 30 development servers, none of which has documentations, and also none of which has a firewall(some security). they say they dont need it, since it's only IP addresses, and is not known to the public.
Karl
kb244@kb244.com

http://www.kb244.com

Experienced in : C++(both VC++ and Borland),VB1(dos) thru VB6, Delphi 3 pro, HTML, Visual InterDev 6(ASP(WebProgramming/Vbscript)

http://www.brainbench.com/transcript.jsp?pid=629151

 

[Advocate]

One of the top questions i always ask of a prospective client ... "is the application documented"

Ivariably, the answer is NO but at least it is out in the open and stated during project where necessary

I have found that most clients are not willing to pay extra time to document but i always try to comment code where possible - not only to assist myself but the next poor sucker who comes along after me ...

I have also come across programmers who deliberately do not want to document/comment so that their little 'empire' is a little safer ...

I tend to sell myself as a troubleshooter specialising in 'undocumented' apps requiring reverse-engineering and fixing ... i have plenty of work !

Best of Irish Luck, David.
djwilkes@hotmail.com