Improving documentation

[P Kishor]

Interesting thread, this, and I've gone and changed its subject.

On 8/19/06, Dylan Beaudette <dylan.beaudette at gmail.com> wrote:
> On Saturday 19 August 2006 18:25, Zenon Panoussis wrote:
..
>
> > > As with all FOSS projects, please feel free to
> > > contribute to the documentation. I know that the GRASS team is always
> > > looking for this type of help.
> >
> > At this point I am not capable of writing real documentation without
> > misleading the reader to commit all my mistakes all over again. All
> > I can do is be verbose in my postings and thereby hopefully of use
> > to the next guy googling (why is the list archive password-protected?).
> > The problem however - which is not specific to grass but very common
> > in FOSS in general - is more fundamental than that. For example, take
> > a look at http://mapserver.gis.umn.edu/docs/reference/mapfile/join .
> > It says "Please note this particular documentation is in a state of
> > flux while I do a bit of source code review..." If I'm reading this
> > correctly, one person wrote the code and no documentation, and another
> > person is struggling to write the documentation out of the code. It
> > shouldn't be like this, code should never be committed unless all the
> > documentation, from man page to reference and howto, is committed at
> > the same time.
>
> Agreed. I have struggled with the same issues in both mapserver and other such
> projects. Unfortunately documentation is not always written at the same speed
> as the code. If you feel strongly about this, bring it up with the OSGeo
> people- and people will probably listen.
>

er, hm.

Zenon, I feel your pain (you will see so in another post of mine soon
;-) ), in fact, I am sure most of us do/have at some time or the
other. I have been struggling for a while with documentation, or lack
thereof, with some of the more esoteric tools. The more a tool is
used, the more documentation is likely to develop for it, so while it
is totally justified to feel the pain, even "whine" if required (is
good for the soul), the only way forward is to add to the docs, add
tutorials, how-tos, etc., in as explicit and step-by-step language as
possible. Every single time you succeed at a task, just note down the
steps and put it somewhere -- in the official docs, on the wiki, on
your own website so it gets google-ified, whatever. No matter how
immaterial or inconsequential it may seem, someone, somewhere will
save a lot of head-banging.

Many thanks,

-- 
Puneet Kishor http://punkish.eidesis.org/
Nelson Inst. for Env. Studies, UW-Madison http://www.ies.wisc.edu/
Open Source Geospatial Foundation https://edu.osgeo.org/