[GRASS-dev] Call for documentation help

The GRASS team needs your help. As you all are well aware, GRASS is enormously sophisticated spatial analysis sophisticated. This also makes it equally complicated and sometimes baffling for users, with over 300 individual modules. GRASS has a top notch integrated and contextual help system. BUT we need help in making the most of the help system.

As with all open source software, the development team is a group of dedicated volunteers who work hard (in addition to their regular jobs) to create the first rate software that you all use. They are also very responsible in trying to document the program modules they code and maintain.

This is where your help is needed. In spite of best intentions and efforts, development team members with coding skills need to put most of their always limited time into writing and maintaining the code that makes GRASS such a powerful and versatile software package. Many of you in the GRASS community are expert users even if you do not have expertise in programming. It is also clear from the traffic on this list that you are regularly willing to share your expertise with others by answering questions.

Would some of you be willing to join the development team to help manage and improve the GRASS documentation and help system? You don't need to be proficient at programming, and because this is a team effort, you don't even need to know all parts of GRASS. What is needed is sufficient knowledge of some GRASS modules to help improve and maintain their documentation pages, a little bit of html (the help pages are in very basic html), and a desire to work cooperatively to improve GRASS. Here is a partial list of roles that are needed.

Individual module management:
-Add or improve examples. Examples of how to use a module to get different results is very helpful
-Add or improve example graphic in modules. Screen shots are often worth many words
-Improve and enrich descriptions in English. In many cases, documentation was written by valiant souls for whom English is a 2nd (or 3rd or 4th) language. Native speakers are needed to enrich these descriptions.
-Add or improve non-English versions of the documentation. GRASS is trying hard to be international and is used around the world. Much of the operational language of the modules have been translated to other languages (though a lot more help is needed in this too). Help and doc pages in other languages would make GRASS much more usable globally.

Overall:
-Documentation management. Someone or ones to mangage a team of documentation helpers, ID holes and weak spots in the documentation, coordinate with the coding team, and think about documentation standards.

If you are interested and willing to contribute a small part of your time to help others use GRASS, please respond to the GRASS Developer list <grass-dev@grass.itc.it> and copy the GRASS project team leader, Markus Neteler <neteler [at] fbk.eu>

Michael

--

Professor of Anthropology
Director of Graduate Studies
School of Human Evolution & Social Change
Center for Social Dynamics & Complexity
Arizona State University

Phone: 480-965-6262
Fax: 480-965-7671
WWW: http://www.public.asu.edu/~cmbarton

I would add, wrt examples, “try to build working examples using the demo data available” (spearfish, IMO; we should think about the new demo for 7.0). We should probably use a system not unlike R’s demo() command or python’s doctests, where the code examples within the docs may be extracted and executed. This might also be merged into the regression testing system.

Daniel.

On 11/4/07, Michael Barton <c.michael.barton@gmail.com> wrote:

The GRASS team needs your help. As you all are well aware, GRASS is
enormously sophisticated spatial analysis sophisticated. This also makes
it equally complicated and sometimes baffling for users, with over 300
individual modules. GRASS has a top notch integrated and contextual help
system. BUT we need help in making the most of the help system.

As with all open source software, the development team is a group of
dedicated volunteers who work hard (in addition to their regular jobs)
to create the first rate software that you all use. They are also very
responsible in trying to document the program modules they code and
maintain.

This is where your help is needed. In spite of best intentions and
efforts, development team members with coding skills need to put most of
their always limited time into writing and maintaining the code that
makes GRASS such a powerful and versatile software package. Many of you
in the GRASS community are expert users even if you do not have
expertise in programming. It is also clear from the traffic on this list
that you are regularly willing to share your expertise with others by
answering questions.

Would some of you be willing to join the development team to help manage
and improve the GRASS documentation and help system? You don’t need to
be proficient at programming, and because this is a team effort, you
don’t even need to know all parts of GRASS. What is needed is sufficient
knowledge of some GRASS modules to help improve and maintain their
documentation pages, a little bit of html (the help pages are in very
basic html), and a desire to work cooperatively to improve GRASS. Here
is a partial list of roles that are needed.

Individual module management:
-Add or improve examples. Examples of how to use a module to get
different results is very helpful
-Add or improve example graphic in modules. Screen shots are often worth
many words
-Improve and enrich descriptions in English. In many cases,
documentation was written by valiant souls for whom English is a 2nd (or
3rd or 4th) language. Native speakers are needed to enrich these
descriptions.
-Add or improve non-English versions of the documentation. GRASS is
trying hard to be international and is used around the world. Much of
the operational language of the modules have been translated to other
languages (though a lot more help is needed in this too). Help and doc
pages in other languages would make GRASS much more usable globally.

Overall:
-Documentation management. Someone or ones to mangage a team of
documentation helpers, ID holes and weak spots in the documentation,
coordinate with the coding team, and think about documentation standards.

If you are interested and willing to contribute a small part of your
time to help others use GRASS, please respond to the GRASS Developer
list <grass-dev@grass.itc.it > and copy the GRASS project team leader,
Markus Neteler <neteler [at] fbk.eu>

Michael

Professor of Anthropology
Director of Graduate Studies
School of Human Evolution & Social Change
Center for Social Dynamics & Complexity
Arizona State University

Phone: 480-965-6262
Fax: 480-965-7671
WWW: http://www.public.asu.edu/~cmbarton


grass-dev mailing list
grass-dev@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass-dev


– Daniel Calvelo Aros

Hi,
just noting: there is already great new demo dataset for GRASS
available. See

http://www.grassbook.org/data_menu3rd.php

The documentation should IMHO be updated according to it.

R demo() is good. I would suggest new "--demo" flag, which could run
small demo script (demo.sh in each modules directory). What do you
think?

Jachym

Daniel Calvelo píše v Ne 04. 11. 2007 v 15:13 -0500:

I would add, wrt examples, "try to build working examples using the
demo data available" (spearfish, IMO; we should think about the new
demo for 7.0). We should probably use a system not unlike R's demo()
command or python's doctests, where the code examples within the docs
may be extracted and executed. This might also be merged into the
regression testing system.

Daniel.

On 11/4/07, Michael Barton <c.michael.barton@gmail.com> wrote:
        The GRASS team needs your help. As you all are well aware,
        GRASS is
        enormously sophisticated spatial analysis sophisticated. This
        also makes
        it equally complicated and sometimes baffling for users, with
        over 300
        individual modules. GRASS has a top notch integrated and
        contextual help
        system. BUT we need help in making the most of the help
        system.
        
        As with all open source software, the development team is a
        group of
        dedicated volunteers who work hard (in addition to their
        regular jobs)
        to create the first rate software that you all use. They are
        also very
        responsible in trying to document the program modules they
        code and
        maintain.
        
        This is where your help is needed. In spite of best intentions
        and
        efforts, development team members with coding skills need to
        put most of
        their always limited time into writing and maintaining the
        code that
        makes GRASS such a powerful and versatile software package.
        Many of you
        in the GRASS community are expert users even if you do not
        have
        expertise in programming. It is also clear from the traffic on
        this list
        that you are regularly willing to share your expertise with
        others by
        answering questions.
        
        Would some of you be willing to join the development team to
        help manage
        and improve the GRASS documentation and help system? You don't
        need to
        be proficient at programming, and because this is a team
        effort, you
        don't even need to know all parts of GRASS. What is needed is
        sufficient
        knowledge of some GRASS modules to help improve and maintain
        their
        documentation pages, a little bit of html (the help pages are
        in very
        basic html), and a desire to work cooperatively to improve
        GRASS. Here
        is a partial list of roles that are needed.
        
        Individual module management:
        -Add or improve examples. Examples of how to use a module to
        get
        different results is very helpful
        -Add or improve example graphic in modules. Screen shots are
        often worth
        many words
        -Improve and enrich descriptions in English. In many cases,
        documentation was written by valiant souls for whom English is
        a 2nd (or
        3rd or 4th) language. Native speakers are needed to enrich
        these
        descriptions.
        -Add or improve non-English versions of the documentation.
        GRASS is
        trying hard to be international and is used around the world.
        Much of
        the operational language of the modules have been translated
        to other
        languages (though a lot more help is needed in this too). Help
        and doc
        pages in other languages would make GRASS much more usable
        globally.
        
        Overall:
        -Documentation management. Someone or ones to mangage a team
        of
        documentation helpers, ID holes and weak spots in the
        documentation,
        coordinate with the coding team, and think about documentation
        standards.
        
        If you are interested and willing to contribute a small part
        of your
        time to help others use GRASS, please respond to the GRASS
        Developer
        list <grass-dev@grass.itc.it> and copy the GRASS project team
        leader,
        Markus Neteler <neteler [at] fbk.eu>
        
        Michael
        
        --
        
        Professor of Anthropology
        Director of Graduate Studies
        School of Human Evolution & Social Change
        Center for Social Dynamics & Complexity
        Arizona State University
        
        Phone: 480-965-6262
        Fax: 480-965-7671
        WWW: http://www.public.asu.edu/~cmbarton
        
        _______________________________________________
        grass-dev mailing list
        grass-dev@grass.itc.it
        http://grass.itc.it/mailman/listinfo/grass-dev

--
-- Daniel Calvelo Aros
_______________________________________________
grass-dev mailing list
grass-dev@grass.itc.it
http://grass.itc.it/mailman/listinfo/grass-dev

--
Jachym Cepicky
e-mail: jachym.cepicky@gmail.com
URL: http://les-ejk.cz
GPG: http://www.les-ejk.cz/pgp/jachym_cepicky-gpg.pub

Jachym Cepicky wrote:

just noting: there is already great new demo dataset for GRASS
available. See

http://www.grassbook.org/data_menu3rd.php

The documentation should IMHO be updated according to it.

I would think it would be more productive to first focus on adding examples to
help pages that do not have one, rather than spend lots of time remaking
existing examples using another dataset. And even when all modules that
usefully could have an example* have one, before working on redoing Spearfish
examples we might work on examples which do not use a known & reproducible
dataset.
All examples that use a sample dataset should be stating which one they use.

[*] e.g. there is little point adding an example for d.erase

The immediate question then becomes which dataset to use for new examples.

Hamish

__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com

"Updating GRASS Documentation" how-to [1].

[1]http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation

Maciek