[prev in list] [next in list] [prev in thread] [next in thread] 

List:       grass-user
Subject:    [GRASS-user] RE: Document management
From:       epatton () nrcan ! gc ! ca (Patton, Eric)
Date:       2008-01-29 10:03:06
Message-ID: CA803441152AAE40935609509953BAD201075F8C () s0-ott-x4 ! nrn ! nrcan ! gc ! ca
[Download RAW message or body]

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


[prev in list] [next in list] [prev in thread] [next in thread]