This might just be me, but without an automated process to determine that
information (which it can be done by doing some programming) this is not an
effort that will pay off in the end. If I was a programmer and knew that
*some* of the information was right, I would always end up going to the
source code so I didn't shoot myself in the foot. It needs to *always* be
right by having it regenerated at least once a day (i.e. in nightlies).
Note that there is an entire midrange group devoted to this subject of
documenting RPG programs (ILEDocs-Midrange I think). I am on the mailing
list but haven't had much time to contribute. Check it out here:
http://sourceforge.net/projects/iledocs/
HTH,
Aaron Bartell
http://mowyourlawn.com
-----Original Message-----
From: midrange-nontech-bounces@xxxxxxxxxxxx
[mailto:midrange-nontech-bounces@xxxxxxxxxxxx] On Behalf Of Mike
Sent: Friday, August 24, 2007 10:45 AM
To: Non-Technical Discussion about the AS400 / iSeries
Subject: 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.
--
Mike Wills
http://www.linkedin.com/in/mikewills
Blog -
http://mikewills.name
Podcasts -
http://podcastmike.com
--
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.
midrange.com
