About documentation

[Mitchell N Charity]

   [...] There seem to be some undocumented features of the language
   of some importance -- or at least they were quite hard to find
   using the top-level index.  These features include such things as
   the simple way to assign and access cells using operators instead
   of functions.  Would a new user know that these operators are
   available by looking up cells?  [reformatted]

You might find
  VirtualManual
  http://www.vendian.org/oz/wiki/index.cgi?VirtualManual
of interest.

"Extensive but scattered" is my own take on the Mozart/Oz documentation.
Something experienced users can work around, but which is spectacularly
bad for new and prospective users.

As Kevin Glynn points out, cells are indeed documented... but piecemeal,
in several different places.

(The VirtualManual turns out to link the places mentioned.:)

Even for experienced users, the disorder obscures opportunities to
improve the docs (such as as-yet undocumented code and idioms).
I suspect even most experienced users are only using smallish subsets
of the language's capabilities.

For newbies... having to repeatedly do backtracking searches across n
documents can make the learning curve look like an exponential wall.
When the book was on line, folks could start there.  But now, their
best bet is perhaps obscure slides, the unfinished Tutorial, taking
extensive notes (while wading through documentation, distribution
source code, and mailinglist archives), and... unusual perseverance.
Most potential users will of course walk away first.

   In the case of the cell update operators they are used in the Oz
   tutorial and documented in the 'Infix Notations' section of the Oz
   Base Environment document.  How would you suggest improving this?

Create a _small_ number of documentation entry points.
"User Manual" is a must.  "Tutorial", "Reference" and "Libraries" are
other popular candidates.

Consider the entire Mozart/Oz documentation set as a single "document".
It's ok, though not ideal, to have a single topic covered in multiple
places.  But if the places are not all cross linked, that's a bug.
And if the path from document top to topic is not obvious, that's a bug.

Thus all "it's already documented" responses on mozart-users should
include not just the (invariably several) pages, but also the path by
which they are reasonably found.  If the path is non-obvious, it follows
that there is a bug, and thus a concrete documentation todo item.

Consider
   "a simple way to assign and access cells using operators instead of
   functions?"

The document
   "Tutorials / Introductory / Tutorial of Oz"
 (ISSUE: Is this a sufficiently obvious name, given that newbies
  start out unclear on the distinction between Mozart and Oz?
  Perhaps "Oz Language Tutorial" would be better?
  Or "Mozart/Oz Tutorial"?)
contains a section Cells
 (OK: it's indeed visible from the table of contents)
which clearly lists the operators.
 (So we have at least a partial win.
  Though searching for "operators" or "syntax" will fail.)

The document
  "Reference Manuals / Programming Modules and Libraries / The Oz Base
   Environment"
 (ISSUE: This is an unfortunately obscure name.  How about something
  clearer?  Perhaps "Language Manual"?)
has a section Cells
 (OK: it's tolerably visible from the table of contents),
which, err, doesn't mention operators at all.
 (BUG)
The tutorial section doesn't link to the "The Oz Base Environment" section.
 (BUG)
The "The Oz Base Environment" section doesn't link to the tutorial,
despite the tutorial having novel information.
 (BUG)

The same document contains a section "Infix Notations" with lists and
describes all(?) operators.  You have to look through them to find the
cell ones.
"Operator" does not appear in this section's title or index entries.
 (BUG)
"Cell" does not appear in this section's title or index entries.
 (Not ideal, but probably not a bug).
This page is not linked from the "The Oz Base Environment" Cell section.
 (BUG)
This page is not linked from the "Tutorial of Oz" Cell section.
 (Unfortunate, perhaps bug).

So a hypothetical new-user experience given the current topology might be:
  Discover cell operators while reading Tutorial.
  Goal: Find further information.
  "Maybe these links will help?"  Explore links in section.  Fail.
  Back up to documentation directory.
  "Err, which one of these is the language manual?"
  Subgoal: Find language manual.
  Search page for "syntax".  Fail.
  Try "Oz Notation".
  "Ah good, Lexical Notation!:)"
  Lexical Notation.  Fail.
  Context-Free Syntax.  Fail.
  Backtrack to trying to find language manual.
  Try "The Oz Base Environment".
  Subgoal: Find information about "cell operators" in document
  hypothesized to be the language manual".
  "Ah, good a table of contents."
  Search for "syntax".  Fail.
  Search for "operators".  Fail.
  Search for "cells".
  "Ah!:)"
  Cells section doesn't help, and doesn't have any links.
  Fail.
  "Sigh."
  Backtrack to table of contents.
  Try "Index".
  Search for "syntax".  Fail.
  Search for "operators".  Fail.
  Search for "cells".  Multiple hits.  Explore.  None helpful.  Fail.
  Search for ":=".  Hit.  "Infix Notation".
  Succeed.
Though, instead of searching the index for ":=", the user may instead
backtrack up past the "find language manual" and do a full text search
over the whole mozart documentation for "cells", "operators", "syntax",
etc, and only find "Infix Notation" after slogging through those results.
I recall doing something very much like that myself when learning Oz.

Experienced users "just know" about the "Infix Notations" section.
But good luck, for instance, figuring out how to modify a super space
from a subspace, using only the documentation.  Or quickly converting
a nontrivial prolog program into an oz program.  Or so much else.

So, concrete suggestions:
(1) Create a link, "for further information", from Tutorial/Cells to
   BaseEnvironment/Cells.
(2) Link from
   Reference Manuals / Programming Modules and Libraries / The Oz Base
   Environment / Procedures and Cells / Cells
 to
   Reference Manuals / Programming Modules and Libraries / The Oz Base
   Environment / Infix Notations
 for its cell operator definitions.
(3) And also to
   Tutorials / Introductory / Tutorial of Oz / Cells
 for its cell operator list, and (unfortunately brief) usage discussion.
(4) Rename "Infix Notations" to something like "Operators and Infix Notations".
(5) On the "Mozart Documentation" webpage, boldface the links to
 "Tutorial of Oz" and "The Oz Base Environment", to emphasize their
 primary importance.

And perhaps
 Ask a minion, an undergraduate or graduate student, to take this pile
 of documents and knit it together into something which another
 language might call a User Manual.

And perhaps
 Note that MIT Press has historically been _far_ more flexible than
 outfits like Springer, with regard to folks placing books or parts of
 books online.  They actually want to do the right thing.  So while
 they asked "Concepts, Techniques, and Models" be taken offline for
 its debut, it would be worth exploring getting parts of it back online.
 It's still the closest thing we have to a user manual.  The absence of
 which reduces the appeal of mozart/oz, and thus of the book.

And perhaps
 Anyone can create their own documentation pages on the wiki... ;)

Mitchell Charity