Re: Auto-building docs manual

Jon,

I don't care so much about information from the PIs and PRs.
I can see that by reading the code.
I can get around that fast with RDi.

I've been working on programs that are decades old on very big systems
where often if there is a set of header comments in the program it probably
pertains the the previous program it was cloned from and is not relevant to
the current program.

I can read the code and understand it pretty quickly ( well, ok, some of
the older stuff hurts my eyes now ) but finding the bigger picture of where
the program fits into the system is what I struggle with.

That's the stuff you can't find out fast without proper documentation or
time or SMEs all three of which seem to be rare commodities.
I'm not saying every program has to have a novel about the entire system,
but a few comments to give some context can be very helpful.

just my thoughts :-)

On 22 February 2018 at 17:50, Jon Paris <jon.paris@xxxxxxxxxxxxxx> wrote:

Craig,

While I agree that the comments are critical to do a good job, most of the
tools that scan source will extract information from the PIs and PRs so a
minimal set of information is available anyway. The one I mentioned does
not scan the source but others like Paul's do.


Jon Paris

www.partner400.com
www.SystemiDeveloper.com

On Feb 22, 2018, at 12:46 PM, Craig Richards <craig@xxxxxxxxxxxxxxxx>

wrote:

Hi Martin,

I've had the same thoughts for more years than I care to remember ( we

were

talking about this when I was contracted to IBM in the early 90s! and may
have even written a prototype, though it was for the telecom NZ project,
not NZ )
Obviously it's possible and it makes sense for all the reasons that

javadoc

does.

I just never got around to writing my own or seeking out someone else's
solution.

That said, ( and this is no reason not to create/use such a tool ) it's
only ever going to be as good as the putting in the markup...

If I'm honest I would say the most useful documentation I've found to be

my

own visio diagrams with annotations.
Well, I say Visio, but my version is Visio 4 - way before microsoft got
involved and sadly I just can't get that to run in Windows 10.
I can get it to run on my mac in my old copy of VMware Fusion but I can
never get the virtual printing to work properly.
So these days, with the extortionate price that microsoft charge for

visio

it's googledocs drawings for me!

regards,
Craig

On 22 February 2018 at 16:21, Jon Paris <jon.paris@xxxxxxxxxxxxxx>

wrote:

There are already several tools out there already that can do this (and
more) based on the Java Docs type comment definitions.

You can find Paul Tuohy's offering RPGLEDOC here:
http://systemideveloper.com/downloadRPGLEDOC.html <
http://systemideveloper.com/downloadRPGLEDOC.html> - I think it needs
some updates but the base is there.

Others will no doubt point you at other offerings but I don't have time

to

look them up right now.

In summary - there are many things I'd rather have IBM spend their time
and money on rather than reinventing this particular wheel.


Jon Paris

www.partner400.com
www.SystemiDeveloper.com

On Feb 22, 2018, at 11:11 AM, Booth Martin <booth@xxxxxxxxxxxx> wrote:

This has been nibbling on me for a while. It seems reasonable to me

but

what do I know.

Lets say that IBM provided a new kind of comment line designed to be

automatically collected at every compile and then included in a IFS
repository as a manual for that application/library/

department/whatever.

Therefore there would be an automatically assembled Intranet website for
the system.

For example, say, a line which looked like:

//:index':'comment*/

Then we could specify particular comments to be used that could

document, with a built-in index, our own procedures, programs, etc that

are

gathered in one useful place.

--
This is the RPG programming on the IBM i (AS/400 and iSeries)

(RPG400-L)

mailing list

To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related

questions.

Help support midrange.com by shopping at amazon.com with our affiliate

link: http://amzn.to/2dEadiD

--
This is the RPG programming on the IBM i (AS/400 and iSeries) (RPG400-L)
mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related
questions.

Help support midrange.com by shopping at amazon.com with our affiliate
link: http://amzn.to/2dEadiD

--
This is the RPG programming on the IBM i (AS/400 and iSeries) (RPG400-L)

mailing list

To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related

questions.

Help support midrange.com by shopping at amazon.com with our affiliate

link: http://amzn.to/2dEadiD

--
This is the RPG programming on the IBM i (AS/400 and iSeries) (RPG400-L)
mailing list
To post a message email: RPG400-L@xxxxxxxxxxxx
To subscribe, unsubscribe, or change list options,
visit: https://lists.midrange.com/mailman/listinfo/rpg400-l
or email: RPG400-L-request@xxxxxxxxxxxx
Before posting, please take a moment to review the archives
at https://archive.midrange.com/rpg400-l.

Please contact support@xxxxxxxxxxxx for any subscription related
questions.

Help support midrange.com by shopping at amazon.com with our affiliate
link: http://amzn.to/2dEadiD