[Gnuplot-info] Documentation [was Re: Multiple sources on a common X axis]

[zowie <def...@bo...>]

Documentation in general is hard, and presenting information in a way that end-users
can read is a skill that is quite different from presenting it in a way that 
works for experts.

My favorite example of the pitfalls was the three-line instruction manual that
used to appear on emacs’ front page by default, back in the 1990s.  It read 
something like this:

   The expression “C-“ means to hold down control while pressing the key. 
   To load a file, type “C-X F”.  For a self-help tutorial, type “C-H T”.  
   To quit, type “C-X C-C”.

I encountered that text as a graduate student in the Physics Dept. at 
Stanford University in 1990.  For the next few years, I would tell new 
students in my research group to “just fire up emacs, and follow the 
directions to the tutorial”.  Out of about 8-10 people to whom I told that 
(remember, these were pretty smart people) zero of them actually found
the self-help tutorial the first try, without being told to read EVERY 
WORD of what was on the screen.

It turns out that it’s very hard for people to find text in the middle of other
text — we’re not natural greppers.

The gnuplot documentation suffers from the same sort of fallacy, in spades.
As an expert I still have trouble finding items in it.  For example, I recently
had trouble with single vs. double quotes in our Perl front-end module
(PDL::Graphics::Gnuplot), because despite multiple reads it was not obvious to me
from the documentation that those two types of quote are interchangeable and 
behave slightly differently within gnuplot.

That’s not to chastise the team — Ethan and Hans-Bernhard and everyone else
have created (and continue to maintain) something phenomenally useful and 
flexible.  Just to acknowledge that many of the support issues on this list
(and tons of “invisible” ones that never get mailed here) reflect a need
to improve the documentation, rather than a failure of the user base
or holes in the code itself.

Cheers,
Craig


> On Jul 29, 2016, at 7:30 AM, Alan Corey <ala...@gm...> wrote:
> 
>> It took me quite some time to figure out a few things. This might keep
>> some people away from using gnuplot.
> 
> Who takes time to read documentation?  I mean, I have, but my best
> resource for looking up how to do something is to look at how I did it
> a year ago.  That's true not only for Gnuplot.
> 
> One thing that might help is to somewhere on a web page have tiny
> (320x200 or so) thumbnails of different plot types that are linked to
> maybe example plot scripts and/or into the documentation where it
> talks about using some feature.  I thought Gnuplot had a "concept
> index", something I use does, in addition to a normal index.
> 
> But that's part of my point, if you use a few dozen different programs
> and each one has hundreds of pages of documentation there isn't time
> in a lifetime to read it all.  It's good that the documentation
> exists, but having maybe a few different ways of finding what you're
> looking for in it is good too.  And this seems to be more of a problem
> in things written by committees or multiple people or at different
> times.  Lazarus for example is potentially a great program with
> thousands of pages of documentation spanning a couple decades but you
> can't find anything in it.
> 
> So I look up how I did it last time.  I use the PDFs and online
> documentation too.
> 
> ------------------------------------------------------------------------------
> _______________________________________________
> gnuplot-info mailing list
> gnu...@li...
> Membership management via: https://lists.sourceforge.net/lists/listinfo/gnuplot-info
>