Re: Using a Wiki for RPG documentation

I am not documenting everything in the program. That would make me go nuts.
I type a summary of what the point of the program is, then document what
resources it uses. An example:

NCUP02 - Employee Maintainance
Modified: 2007/08/21 19:30 by username - Categorized as: CustomerService,
Library_NCLIBR, Programs
» NCUP02 - Employee Maintainance

Employee Maintainance program.

Files Used

* NCEEIDP (U)
* NCDEPTP
* NCDIVSP

Parameters

* addRecOnlyIn (I|N)

Modules/Subprocedures Used

* CenterText
* DepartmentCodePrompt
* DivisionCodePrompt

Change Log

2007-08-24
*changed names of display fields

So as you can see, there isn't anything too specific. I agree with your
problems. But with discipline, it can be updated as we edit or finish it up
to keep it up-to-date. And as long as we realize that it may not be 100%
up-to-date, it would work for a great guideline of what it does and what it
uses. Do you think there should be more information? Less information?

On 8/24/07, Walden H. Leverich <WaldenL@xxxxxxxxxxxxxxx> wrote:

I would look to automate the wiki-build process by having a program that
"reads" the rpg source, and maybe defining some standard comments that
need to be in the source, eg. javadoc.

However, I also have a concern about what you're doing in general,
unless you have really strong management support for maintaining the
documentation it's going to go out of sync w/the real application, and
wrong-documentation is much more dangerous than no documentation at all.
I actually do like documentation, but it should be driven from
comments/code in the actual source members, not maintained separately.
I've seen it too many times where a program change is made because the
documentation says the program works "this way" but the docs are out of
date and the change breaks all sorts of stuff because the program really
works "that way". :)

-Walden

--
Walden H Leverich III
Tech Software
(516) 627-3800 x3051
WaldenL@xxxxxxxxxxxxxxx
http://www.TechSoftInc.com

Quiquid latine dictum sit altum viditur.
(Whatever is said in Latin seems profound.)

--
This is the Non-Technical Discussion about the AS400 / iSeries
(Midrange-NonTech) mailing list
To post a message email: Midrange-NonTech@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: http://lists.midrange.com/mailman/listinfo/midrange-nontech
or email: Midrange-NonTech-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at http://archive.midrange.com/midrange-nontech.