Syntax for Pretzel Logic statements

[Ken d'Albenas <kendal -at- AUTOTROL -dot- CUC -dot- AB -dot- CA>]

Jack Shaw asks,


>  Writers in my area are always looking for a foolproof . . .
>  way to define software statement syntax that would not
>  be misunderstood.

>  . . . Has anyone out there a breadth of experience with
>  documenting software statement syntax that has been
>  well-received?

>  Jack Shaw
>  Software AG
>  Truth-in-Documenting Dept.
>  Darmstadt, Germany


If I don't have "a breadth of experience," I do at least have
a wealth of agony on this topic.  Here are a few thoughts.

First, which of the following do you mean by "syntax?"

1. Documentation like this (which some manuals call "synopsis"):

     CONV,<informat{(DRAW),CART}>,<outformat{(DMS),DEC}>
      ,<zone{1-60}>[,TI],p1 ^
     |...................|

     which incorporates symbology like this:
     - UPPER CASE = literal keywords
     - lower case = parameter name
     - <x> = defaultable parameter
     - [x] = optional parameter
     - (x) = default value
     - {x,y} = list of possible values
     - , = literal parameter delimiter
     - ^ = RETURN key
     - |....| = repeatable parameter

OR

2. Do you mean the very way a statement is designed?
   E.g., whether the CONV statement above is designed as shown,
   or one of a million other ways, or broken up into separate
   statements.


I've found that the amount of difficulty (challenge?) in #1 is
directly proportional to the square of the Pretzel Logic Index
of #2.  However, the Pretzel Logic Index is subjective.  What
right-brain users see as a dog's breakfast may be perceived by
your "propellerheads" as _elegance_.

Thus does the technical writer have a vested interest in
participating in software design from the ground up.  You know
your intended audience.  (You _do_ know whom you're going to be
writing for, don't you?)  The more intuitive* the architecture
of the statements, the easier it will be to document the syntax,
and the higher your signal/noise ratio (or hit/miss ratio) will
be.

 * In this context, "intuitive" means "what the users are
   already used to."

I've had _some_ success with this over time.  A little 2-way
psychology goes a long way.  If the programmers get tired of
gadfly technical writers pointing out the flaws in existing
statement design, or bemoaning the difficulty in communicating
the syntax, they will tend to come to the writers at the design stage
of future projects.  They will figure (rightly) that anyone who
has a finger in the pie can't come back later to complain about
its flavour.

A menu-driven interface is also a great way to do an end run
around statement syntax problems.  If the user can answer prompts for
input in natural language, command statements are no longer needed.
(After all, command statements are just a primitive kind of
interface themselves; the real action happens at the level of
machine language.)

I had a special success in this regard with a textual menu interface
for a batch program, which built up ASCII files for overnight
processing.  The programmer and I worked together on figuring out
what we wanted, how to organize and phrase the prompts,
how many levels to use, how to review existing settings, and how
to escape from various levels of nested menus.  I got to try to
break the interface - something I have a talent for - and by the
time we were finished, it was idiot proof.  The programmer was
literally ecstatic with the product, and wrote e-mail to every
manager higher up in his and my food chain, saying how much he
valued my participation.

Something even more satisfying than praise before the suits,
however, was the fact that my manual for the product is just six
pages long.  The interface explained itself.  Now that's what they
mean by minimalist documentation.


Just a few thoughts.


Cheers,

Ken d'Albenas                  (not Kendal Stitzel)
kendal -at- autotrol -dot- cuc -dot- ab -dot- ca
Flames to:  kendal@/dev/not
(-::

===================================================
"I always pass on good advice. It is the only thing
to do with it.  It is never of any use to oneself."
  - Oscar Wilde
===================================================

*****************************