About documentation

[Thomas Packer]

I like the wiki.  Thanks.

tomp


On Monday 30 August 2004 12:57, Mitchell N Charity wrote:
>    [...] 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
> ___________________________________________________________________________
>______ mozart-users mailing list                              
> mozart-users at ps.uni-sb.de
> http://www.mozart-oz.org/mailman/listinfo/mozart-users
>
>      You are invited to The 2nd International Mozart/Oz Conference (MOZ
> 2004) Charleroi, Belgium, Oct. 7-8, 2004                   
> http://www.cetic.be/moz2004

-- 

Ciao,
TomP in BYU CS NLP

I have changed my email address to:
tpackers at byu.net

Check out my way of indexing information:
http://www.ontolog.com/LinkRanker
````````````````````````````````````````````````````````````