PDA

View Full Version : How many of you folks really DOCUMENT and DOCUMENT your programs?


singularity2006
10-07-2003, 05:29 AM
So how many of u folks diligently provide firm and detailed documentation of the programs that you program? How far do you go in documentation?

dead_eye
10-07-2003, 06:03 AM
Very far. I document every function, every class I write. What it does, what it's supposed to do, what you have to be careful of (special cases and stuff). Everything goes into MS Word. When I was developing chemisty educational software, I always had a stack of papers or some sort of notebook right next to the computer filled with diagrams, descriptions, things TODO, things to fix, dates, and so on. I miss those days... headlines and deadlines :).

EricChadwick
10-07-2003, 03:34 PM
I am the document guy at our company, although an artist first. I actually enjoy figuring out how to write technical docs such that the concepts come across clearly. It's a fun challenge.

I like that the process of figuring out how to document a feature will force me to fully understand it, bringing up questions as I go that I wouldn't encounter as quickly during actual production.

The one thing I dislike the most is the iterative process of it... keeping docs up to date as features progress along. It gets old editing the same old doc month after month. But it's ultimately useful.

Commenting source is also very helpful, from what I've seen. Especially when collaborating with others, but it also helps jog the memory in reviewing/updating your own work.

One thing we're battling a little at this point is the issue that people generally don't read when they try software the first time... most people eschew reading anything and just jump right in (me incl.). Ultimately we came to the conclusion that serious folks (those with the buying power) will read the docs, and be very grateful for them, which leads them closer to an actual purchase.

Anyhow, a couple thoughts running around my head these days. I get the impression that most new software has very little in the way of in-depth documentation.

Good topic, thanks.

playmesumch00ns
10-07-2003, 03:44 PM
Use doxygen to rip documentation straight out of your code comments.

singularity2006
10-08-2003, 05:36 PM
that all sounds well and good. How many of u landed your job only because of how well u document? o.0

EricChadwick
10-08-2003, 06:05 PM
Mr. Facetious. :)

I can honestly say it was a factor. Not a major one, but definitely a plus.

I'm not an engineer though, just an artist. My portfolio/reel carried a lot of weight, as did my experience, and my management experience.

But also it's difficult to find artists who are comfortable with technical issues. So the documentation I had done spoke directly to that.

Well, anyhow, an artist's hiring experience is probably not all that applicable to programmers/engineers.

Derlaine
10-13-2003, 12:36 AM
deleted text because i can't delete the post

CGTalk Moderation
01-16-2006, 07:00 AM
This thread has been automatically closed as it remained inactive for 12 months. If you wish to continue the discussion, please create a new thread in the appropriate forum.