[GRASS-user] RE: Document management

[Patton, Eric]

>Wesley,
>
>cleaning up my mail box I found your message (see below).
>We would be interested to know you involved - do you see
>a chance?
>
>Eric Patton is coordinating the documentation efforts, I am
>sure he would welcome you to help out with polishing the GRASS
>documentation.
>
>Best regards
>Markus Neteler

Hello Wesley,

--- posting to the grass users' list in case there's any other help lurking out there ;) ---

I would certainly welcome your assistance! My general approach has been to try to update the docs in some sort of logical sequence, i.e., I'm starting with the raster html help pages and working through them alphabetically, if only so that I can track my edits in a master spreadsheet. If a Grass user on the mailing list files a bug report for one of the docs, or voices concerns about the documents on the mailing list, I try to address that issue as soon as possible, then basically resume where I left off in the spreadsheet. The unfortunate result of this is that there are many docs that I won't get to for quite a while, such as the vector docs. There are also many Grass modules whose function I still don't understand, even after reading existing documentation. So other users in other fields of study are certainly welcome in the documentation effort, as they have different experience with data types and methods that I do not.

I would say work through whatever modules you wish and forward me your edited version of the module's description.html. I can upload it to the svn repository as I have commit privileges. I don't think it is necessary to create a unified diff (diff -u) of your changes; just send me the complete edited html page. 

I can also keep track of which modules people have helped me with, and what edits were done, just so there's no duplication of effort on my part.

Things I like to watch out for:

a) General grammar, spelling, punctuation. These are generally the easiest to do, and can usually be done whether or not you understand the module's function.
b) Overall clarity and wordiness. I try to keep the descriptions clear and concise.
c) Section formatting. The modules should try to keep the documentation headings the same, as much as possible, for consistency (see the link below for recommended section headings)
d) Examples. If a module has existing examples, I test them out in the Spearfish location and see if the syntax for the examples is correct. There should really be an example demonstrating the function of most flags and parameters. If none exist, I'll try to create some and add them in, again using maps from the Spearfish dataset. (Aside: Markus, I haven't been tracking the progress of the North Carolina sample dataset, is this up and running, and available now?)
e) Lastly, I check to see how accurately the documentation describes how the module actually works. This one is the most difficult, as you have to really know! I resort to trial-and-error with the Spearfish sample dataset until I feel confident I understand the function of the module.

Some resources:

http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation

If there's anything I missed or overlooked, let me know. Thanks again for the help, it is much appreciated.

Regards,

~ Eric.