Aaron, I'll check out the site.

On 8/24/07, albartell <albartell@xxxxxxxxx> wrote:

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.

--
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.





As an Amazon Associate we earn from qualifying purchases.

This thread ...

Follow-Ups:
Replies:

Follow On AppleNews
Return to Archive home page | Return to MIDRANGE.COM home page

This mailing list archive is Copyright 1997-2021 by midrange.com and David Gibbs as a compilation work. Use of the archive is restricted to research of a business or technical nature. Any other uses are prohibited. Full details are available on our policy page. If you have questions about this, please contact [javascript protected email address].

Operating expenses for this site are earned using the Amazon Associate program and Google Adsense.