Documentation Tools

[agmorgan]

Assuming that you do document your code
What method do you use?
Do you have a Word/HTML document running parallel to your code or do you just document in the code?

I found that the comments in code are hard to follow but the parallel documentation quickly got out of date (mostly due to me not keeping the documentation up with the code)

Recently someone showed me a Documentation Tool for Python that parsed the comments in the code and created an HTML file out of it.

Does anybody use anything like this for VB?

What tools can you recommend?
Are there any free ones that are as good as the commercial ones?

[RhinoBull]

Have no clue how good/bad the following products are so give it a try:

http://www.codework.com/codeprint/product.html
http://www.vbdocman.com/

[RhinoBull]

I've just tried vbdocman and it's very promising.

[RobDog888]

Vbdocman looks like it should do the job, but $58 for the VB6 version may
be too much for some programmers. You could write your own VB IDE Add-In
to do the same thing. Shouldn't be too involved. I would assume that you
just copy each line that hass comments and add them to a textfile or create
a new Word Document - save $$$.

HTH

[RhinoBull]

I would just go with commercial version rather then spending time ...
But personally - Word, Visio, etc are good enough for me when it comes to write documentaion.

[Armbruster]

Hmmmm, at my job those are usually many seperate beasts . . .

I include lots of comments in my code . . .

The buisness analyst creates a Functional Design Document stating how the application will function

The application developer creates the Technical Design Document stating how he got the application to do what the FD says it should do

The application developer also writes the Unit Test Script to verify it does what he/she says it does

The application developer also writes the Change Management document to prepare the applications migration to QLTC and then Production

The application developer and buisnesss analyst colaborate on any setup docs, user manuals, help manuals and user setup guides

The buisness analyst writes the User Test Scripts and meets with buisness to verify the application works as intended in QLTC before migration to Production

. . . did I miss any? . . .

oh yeah, the buisiness analyst write the final release memo to buisness

[Bombdrop]

You can get a great free
Document Generator from PSC.

Hope this helps!!!

[RhinoBull]

Hmmmm, at my job those are usually many seperate beasts . . .

I include lots of comments in my code . . .

The buisness analyst creates a Functional Design Document stating how the application will function

The application developer creates the Technical Design Document stating how he got the application to do what the FD says it should do

The application developer also writes the Unit Test Script to verify it does what he/she says it does

The application developer also writes the Change Management document to prepare the applications migration to QLTC and then Production

The application developer and buisnesss analyst colaborate on any setup docs, user manuals, help manuals and user setup guides

The buisness analyst writes the User Test Scripts and meets with buisness to verify the application works as intended in QLTC before migration to Production

. . . did I miss any? . . .

oh yeah, the buisiness analyst write the final release memo to buisness

I wish EVERY business analyst would do his/her job like the one you have ...
In reality not every company can afford such position and if they do - not every BA will actualy write documentation which is usualy forwarded to poor developer so everybody else would just wash their hands.

Cheers

[Dave Sell]

Assuming that you do document your code
What method do you use?
Do you have a Word/HTML document running parallel to your code or do you just document in the code?

Not that this is the best way, but my preferred style is to code something from the ground up without any comments *gasp*.

After I can release a version to a client (or boss, etc..) I then go back and document. This forces me to document from a fresh perspective. I find this helpful because I have a crappy memory and will forget everything about a project if I don't look at it after about 3 months.

As far as visual style, I strongly refrain from putting no-duh comments inside of code blocks like this:

Dim intCounter ' This is used to iterate through For Loops
 
For intCounter = 1 to 10
' ...
Next

Instead, I prefer to put large-ish comment blocks at the top of complex functions, possibly zero comments for no-duh functions, and the top of each module gets a running log of changes to the code post-release.