[GRASS5] documentation

[Moritz Lennert]

On Wed, Apr 24, 2002 at 11:43:33AM +0200, Markus Neteler wrote:
> On Wed, Apr 24, 2002 at 10:28:52AM +0200, Moritz Lennert wrote:
> > On Tue, Apr 23, 2002 at 09:12:56PM -0500, Helena wrote:
> > > > start a general review of everything that is available, merge usable
> > > > stuff and write whatever is needed.
> [...] 
> > > So I really believe that instead of trying to fix the old book (which
> > > would be a monumental work, as it requires much more than polishing), it
> > > would be actually faster and better to write new on-line tutorial based
> > > on the latest GRASS5 release, rather than rely on GRASS4* materials. We
> > > have already set it up, I think that Markus has a link to it.
> > 
> > There already is a new tutorial ? 
> 
> You can find an outlined version here:
> http://grass.itc.it/gdp/grass5tutor/
> 
> This must be filled with contents now.
> Eventually we should use "docbook" or something
> similar (http://www.docbook.org/)


It looks good. however, it is data oriented, not task oriented as
Helena suggested.

 
> > I have been thinking along the same lines and I would propose somethin
> > like this:
> > 
> > 1) A man page of a manual should contain links to parts of the
> > manual/examples where it is used. A while ago I sent a message to the
> > list, asking whether it would be possible to include a keywords
> > section the man pages which would then be used to link to tutorials
> > (i.e. on the d.rast page have a link to "displaying maps", "using
> > raster data", etc..).
> 
> ... and at least I agreed :-) In fact I already contacted colleagues
> here to generated keywords semiautomated (as it is a huge task for
> nearly 400 pages). But up to now I do not have a good suggestion
> for software to use.

No idea there, but I believe that if a few people are willing to spend
a bit of time at this, we should be able to do this fairly quickly,
especially if we have pre-defined keywords.
 
> > 2) If we use the keywords carefully, we can automatically create a
> > page that lists all the keywords with links to the relevant man pages
> > and more detailed tutorials if the latter exist. This could be the
> > beginning of a tutorial and people could add and maintain small
> > tutorials on one of these aspects. If there is no tutorial, at least
> > the user has all the relevant modules listed.
> 
> Such an index would be very welcome.
> 
> > 3) I think that seen the limited amount of people, this formula allows
> >    incremental growth of documentation, while being usable almost
> >    immediately.
> 
> But I don't think that a tutorial can grow from an index. I stick
> more with Helena's idea of writing task oriented. However, the
> tutorial should not miss such an index.


I guess I was not clear enough. The keywords I was thinking about
would be task-oriented. So we might use the outline you've already
made, or make another, task-oriented one. This would give us an idea
about the keywords to use (corresponding to sections or subsections of
the tutorial (i.e. data_import, data_display, erosion_modelling,
image_rectification, etc, etc). So, if we have the outline and man
pages which contain the respective keywords, it should be quite easy
to automatically create the links to the relevant man pages in every
(sub)section of the tutorial. This would already allow a new user to
go to the section "displaying data in Grass" and, even if there is no
tutorial text, yet, she/he would at least find links to the relevant
man pages. Once we have written a tutorial on how to display data,
there will also be a link to this tutorial. Thus, the tutorial would
be usable almost immediately, and filled up little by little.
(http://grass.itc.it/gdp/grassmanuals/grass50_commands_sorted.html
already contains the same idea, but without links and with each module in
only one category.)

Any developer contributing a new man pages would be asked to include
the keywords she/he thinks relevant. And I and others would make a
deliberate effort to write section tutorials as quickly as possible.

Does this sound reasonable ?

Moritz