[GRASS5] documentation

[Moritz Lennert]

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.
> 
> It would be absolutely wonderful if you could review what is there - some time
> ago
> I suggested to Markus that just giving each document a rating (maybe *, **, ***)
> in terms of how much up-to-date and usable it is would help a lot and then sort
> them by this rating.
> This of course means reading everything and testing those materials that are
> considered
> up-to-date in terms of GRASS5. And of course the rating may need updates from
> time to time.
> So it is quite a bit of work but it would be really useful.

I will look into that, but as you say, it will be a lot of work.

> 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 ? 
 
> I think that it should be more task oriented rather than  "type of data" oriented
> as is the users manual. For example it should have:
> Setting-up a project, Importing Data, Integrating data from different coordinate
> systems, Digitizing, Viewing maps, Working with surfaces, Computi ng the basic
> statistics, etc. For some tasks we already have nice tutorials,  e.g. map algebra
> or nviz, so those could be updated and used directly.
> Also it should be structured for on-line learning, more graphics, and interaction
> than the book's plain text. (for example for our on-line erosion modeling
> tutorial we have the commands linked with manual pages and maps, so you can learn
> everything about the command that you are using by clicking on it and also see
> how your inputs and outputs may look like:
> see http://skagit.meas.ncsu.edu/~helena/gmslab/erosion/usped.html
> or the later version of the whole thing at
> http://skagit.meas.ncsu.edu/~helena/gmslab/reports/CerlErosionTutorial/denix/denixstart.html)
>
> This format (Markus set it up with php instead of frames) would be also more
> suitable for getting more people to work on it.
> And translations should be much easier as a lot of the text could be "bulletized"
> rather than writing complex sentences which are more difficult to translate.
> 
> So that is just a suggestion

But a very goog one ;-)

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

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.

3) I think that seen the limited amount of people, this formula allows
   incremental growth of documentation, while being usable almost
   immediately.


So, if someone could confirm that 1)+2) are possible and maybe point
me into the right directions on how to do it, I am willing to begin
with that. Once the keyword page (i.e. the table of contents of a
task-oriented tutorial) is ready, I (and others) can weed through the
existing jungle and select those documents that should be linked to
from that page. In a third phase we then have to write whatever is missing.


Moritz