About documentation

[Thomas Packer]

Hello

	Another suggestion regarding how to index documentation (but which may be too 
weird for most people to want to try) is this format:

	http://www.ontolog.com/LinkRanker/

	It may look foreign in the context of indexing documentation.  But I'm 
experimenting with it and have some hopes for it.  You could compare this 
approach to the wiki, in that the user community itself would make it more 
complete.  But the Ranker would be a lot easier to refine once the initial 
set of links were all added to the database.  And a user who adds a link 
would not need to know where to put it in a hierarchy.

	The Ranker is based on two simple ideas: "facet based classification" and 
"conditional probabilities".  I like facets better than a rigid hierarchical 
structure for the purpose of finding documentation because you don't need to 
guess how someone else may have classified your target document/concept.  And 
there are often many terms which are descriptive of a document, only a few of 
which need be used to find it.

	You'll notice that it's a little slow right now with a time complexity of 
something like O(n^4), but I hope to figure out how to keep the same 
functionality with a smaller time complexity.  (It was fine when I had around 
100 subjects in the database.)

	What you have in the Ranker's web page is a collection of key words or 
subject terms on the left side, and a sorted list of web pages on the right.  
When you click on a subject, the php script takes that subject as "evidence" 
for wanting a web page link, and then re-sorts all the links according to 
their conditional probabilities.

	Probabilities are based on usage data (common hit counts), so the more people 
search for a web page via a certain subject (or set of subjects), the 
stronger the association will be between the subjects and the web page, and 
therefore the easier it will be to find the same web page the next time you 
(or someone who thinks similarly) tries to find it.  If you don't find your 
page with the first subject, you click on another subject.  (It currently 
uses a noisy-or conditional probability model.)

	There are two ways to facilitate finding the right subjects to click on: (1) 
sorting the subjects list by their own conditional probabilities and (2) a 
letter index into an alphabetically sorted list of subjects.  It's probably 
the sorting of subjects by probabilities that takes the most time in loading 
a new page, so if that is not as useful as the simple alphabet, it could be 
taken out and immediately improve link sorting.

	Here's a demo/tutorial of how to use it:

	Go to the LinkRanker page at the URL given above.

	Notice that there are no links to Oz documentation in the top dozen or so 
links on the right.

	Click on the "O" in the alphabet on the left.

	Click on "Oz".

	You now have a few Mozart/Oz web pages to choose from.

	If you can't already see the CTMCP book that you might be looking for, you 
can then click on "books" below "Oz" on the left side of the page (which is a 
subject I have associated with "Oz" through common use).  Now the top link is 
a web page about that book.

	There are many possible variations of this Ranker idea, as I'm sure you are 
mentally generating for yourself as you critique the current version.  But I 
bet one variation or another could be useful for the Oz documentation.

	ciao,
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
````````````````````````````````````````````````````````````