Re: Oberon/F documentation

Elan Paznesh (icimjs@netvoyage.net)
Tue, 23 Jul 1996 15:39:14 -0700

I'm resending this message because yesterdays message appears not to have
been transmitted properly.

Rowland writes:
>I find myself wanting a framework similar to Oberon/F's--except with
>either the
>source code available or else thorough documentation.

Others have also occasionally mentioned that they find the documentation to
be insufficient. I think we should band together, systematically
investigate the modules delivered with Oberon/F and assemble an exhaustive
online documentation. After all, if we are serious about component
technology then we programers will have to cooperate before our components
can. Programer producitivity is an important economical ressource and a
rich library of 3rd party components will benefit us all. The faster and
better we can all start contributing useful components the faster we can
all get our work done.

Why don't we do the following:

1. Let's identify the modules that are delivered with Oberon/F, (easy
enough)
2. identify which of these modules are documented sufficiently,
3. construct a list of the modules that need to be documented in the order
of urgency,
4. and divide the list up among volunteers who want to contribute part of
the documentation, either because they feel competent to explain the unit
and its purpose or because they want to take the time to investigate it and
are confident that they will be able to come up with some useful
contribution.

The urgency of documenting an item should be determined based on:
1. its sytematic value,
2. a volunteer available to document the module (preferably someone who has
experience using it).
3. current need for documentation.

We should first cover those modules for which there is a current need and
that are of systematic value and for which we have an experienced
volunteer. Secondly, systematic value and experienced volunteer. Third,
systematic value and volunteer willing to research it. Finally, a module
that might not be as important systematicly, but for which there is an
urgent current need to see it documented. (Current documentation
needs should first be delegated to mailing lists. We should try to avoid
not be allowing them to interfere with the more systematic work.)

The status of the documentation will be public domain. It will be made
available to be hosted by anyone who wishes to host it. I will be hosting
it on my companies' web server, which means we definitely have one site.

The format of the documentation report should be systematic.
1. Name of the module.
2. Purpose of the module.
3. Overview of how it works.
4. Summary of functionality it provides.
5. Examples of when one would want to use it, seperated by import and
extend.
6. Brief, complete description of exposed types, consts, vars and
procedures, including their purpose.
7. Usage examples.

The presentation format should be:
1. Dictionary form,
2. Documentation form,
3. How-to form,
4. Tutorial form.

Please let me know your suggestions.

If you think this project is important and that you stand to benefit it by
it, please let me know.

If you wish to make a contribution, for sure let me know.

Please post your response here, send it to the Oberon/F mailing list (Guy
Laden's Oberon/F page for details at
http://www.math.tau.ac.il/~laden/Oberon.html for details) or send me email

icimjs@netvoyage.net.

I'm curious to hear from you.

Elan