Re: Documentation style

[Rik]

On 09/12/2014 09:00 AM, address@hidden wrote:
> Subject: > documentation style question
> From: > "John W. Eaton" <address@hidden>
> Date: > 09/12/2014 08:32 AM
> To: > octave maintainers mailing list <address@hidden>
>
> I'd like to be consistent in the way we document functions like grid that have a number of different options.
>
> In older versions of Octave, we had
>
> ## @deftypefn  {Function File} {} grid (@var{arg})
> ## @deftypefnx {Function File} {} grid ("minor", @var{arg2})
> ## @deftypefnx {Function File} {} grid (@var{hax}, @dots{})
> ## Force the display of a grid on the plot.
> ## The argument may be either @code{"on"}, or @code{"off"}.
> ## If it is omitted, the current grid state is toggled.
> ## ...
>
> so we showed a small number of different forms and explained the valid values for the arguments.
>
> Now we have
>
> ## @deftypefn  {Command} {} grid
> ## @deftypefnx {Command} {} grid on
> ## @deftypefnx {Command} {} grid off
> ## @deftypefnx {Command} {} grid minor
> ## @deftypefnx {Command} {} grid minor on
> ## @deftypefnx {Command} {} grid minor off
> ## @deftypefnx {Function File} {} grid (@var{hax}, @dots{})
> ## Control the display of plot grid lines.
> ##
> ## The function state input may be either @qcode{"on"} or @qcode{"off"}.
> ## If it is omitted, the current grid state is toggled.
>
> so we are enumerating all the options.  The following description no longer seems to apply (what input state?) so it seems like it should be edited.
>
> Do people prefer the current way of listing all the possibilities?  I'm working on adding the zoom function and if documented this way, there will be 10 lines enumerating the different ways it can be called.
>
> Also, why distinguish between Command and Function File now that any function that accepts character string arguments can be called with "command" syntax?
>

The verbosity is a good thing, in my opinion.  The idea is based on two tenets: 1) that people want to use a function quickly, and 2) the human brain is adept at pattern matching.  The way I visualize this Human Interface Design challenge is that the user's problem is a pegboard.  They know that function XXX can solve the problem (put the peg in the hole) but they have to match the shape of the function (square, triangle, circle) to their particular problem (square, triangle, circle).

Now you can write the documentation in Backus-Naur Format, but then it takes a lot of mental effort to unpack what is going on.  Ignoring the fact that this would be confusing with Octave's own syntax you could write the documentation as

grid [ [minor] on|off ]

Ugh, that is pretty opaque.  With the current documentation I can just scan down the list and make the educated guess that 'grid on' will enable the plot grid.  This not only works, my guess does the right thing, but I don't need to read the full docstring which saves time.  People are generally lazy and they like it when "stuff just works" without having to read a lot of background material.  It would be super annoying, for example, if you had to read a manual before using a screwdriver.  A screwdriver should "just work".  Octave, as a tool for technical people who have no wish to become computer scientists, should just work as often as possible without having to read the manual. 

As for {Command} versus {Function File}, we have plans to actually eliminate that field entirely.  The discussions happened a while ago, but maybe we'll get around to implementing it sometime.

In general, I have been trying to document the most common usage pattern so that a user can apply pattern matching.  It's true that people who program frequently in Octave would know that, in the absence of opening and closing parentheses, all arguments are delivered as strings to the function.  But that requires building up familiarity with Octave.  People just want to grab a piece of code, tweak it slightly, and run it.  Of the two possible choices to document,

grid ("on");
    OR
grid on

I chose the latter because it is more common and involves less typing.

As an aside, if you take a look at Matlab documentation you'll find that they are trying to move in this direction too.  I think this is a good HID decision on their part.

--Rik