[GRASS-dev] v.surf.bspline man page - Man page improvement day

GRASS GRASS developer
1

Excellent. Is it technically feasible to involve the whole
user community in this? Or would it be easier to restrict
to devs with SVN write access?

Ben

On 01/19/2011 12:42 PM, Markus Metz wrote:

On Wed, Jan 19, 2011 at 9:14 AM, Anne Ghisla <a.ghisla@gmail.com> wrote:

On Wed, 2011-01-19 at 08:51 +0100, Markus Neteler wrote:

On Wed, Jan 19, 2011 at 12:37 AM, Dylan Beaudette
<debeaudette@ucdavis.edu> wrote:

On Tuesday, January 18, 2011, Benjamin Ducke wrote:

That's reassuring, thanks Markus.
Incidentally, since HTML housekeeping is such a boring
chore but so crucial: Do you guys think it would make
sense to have a "man page improvement day", similar to
a code sprint, but with the whole community dedicating
perhaps a day to finding problems in man pages and fixing
them?

I am not just talking about correcting errors, but also
rephrasing things that are hard to understand or elaborating
on aspects that aren't explained verbosely enough.

Ben

Excellent idea! I would participate.

Me, too.

Also the sphinx'ization (http://trac.osgeo.org/grass/ticket/151) comes to mind.

Me too!

Me too. It seems I started something here by forgetting to remove a
paragraph. I always wanted to update the lidar tools man pages but
never got around to do it...

Markus M
_______________________________________________
grass-dev mailing list
grass-dev@lists.osgeo.org
http://lists.osgeo.org/mailman/listinfo/grass-dev

------
Files attached to this email may be in ISO 26300 format (OASIS Open Document Format). If you have difficulty opening them, please visit http://iso26300.info for more information.

2

Benjamin wrote:

Excellent. Is it technically feasible to involve the whole
user community in this? Or would it be easier to restrict
to devs with SVN write access?

one unfortunate thing about writing documentation is that you have to be
both an expert in the nuances of the subject, and at the same time be
able to look at it from the eyes of a newcomer. it's rather a tricky
balance to craft the words just right. sometimes the wording is just bad,
other times the words are a little awkward on purpose, to get the reader
to think about the idea from the right POV.

e.g. to teach first-year undergraduate students you have to simplify things
a great deal to not bury them, but at the same time you have to be very
careful that those simplifications do not go over the top and become lies
which they will later trust & so make it harder for them to learn the
details later on. (this paragraph was not awkward on purpose, just regular
awkward :slight_smile:

as per usual, patches welcome from all; those with commit access are
responsible for committing, and they are personally responsible for
reviewing and signing off on anything and everything they commit.

Hamish