[racket-dev] Racket documentation

Comments on the below discussion and possible implementation ideas.

User-contributed comments should be annotations to the documentation.  They could then be fetched using JS (Ajax) from the local copy when an internet connection is available, and if there is no internet connection the annotations simply won't appear.  They could be icons on the side (associate each annotation with a function call or some other place marker in a page of documentation) and expand when clicked on.  This allows local copies to be as useful as they are now while adding in the community portion when possible.

Versioning issues include:
- An annotation applies to a specific Racket version, and may at some point no longer apply
- An annotation gets folded into the official documentation, so no longer needs to be visible.

So each annotation should include a start and end Rkt version number for display to handle the first issue.  The second could be handled by setting the end version to expire the comment when adding it to the official documentation (or by some other field if this is a bad idea).

Some other emails seem to dislike the wiki approach to documentation.  This would then suggest just keeping a list of user comments rather than one chunk of wiki text per documentation location (i.e. per function).  This list could be tagged with author user name, or just kept anonymous.  Still, even with comments some are more useful than others, so perhaps a community voting system to move the good comments to the top of the list. (Like in Yahoo! questions and many other question-answer forums.)

The tie-in to the current documentation is in finding a way to determine Racket version (do we need a separate documentation version number?), documentation page, and functions within the documentation.  Then when we display it we just match up the comment lists to the right location in the display.  Hopefully that leaves the existing Scribble system untouched, except maybe to add some hints for the tie-in and the JS code to load comments in the local docs.

-Everett

On Sep 21, 2010, at 11:18 PM, Eli Barzilay wrote:

> On Sep 21, Matthias Felleisen wrote:
>> On Sep 21, 2010, at 4:58 PM, Eli Barzilay wrote:
>> 
>>> And a side-comment -- having an on-line documentation is probably
>>> going to make lots of people who follow the repository happy,
>>> since compiling it is where the biggest chunk of time is spent.
>> 
>> No, no. See my comment. The improvements to the docs have to flow
>> back to the repository version in some way.
> 
> No, no -- see *my* comment...  The improvements *should* flow back to
> the repository -- of course -- that's the whole goal.  The thing that
> I'm talking about in the above is that the default mode for setup is
> to *not* build the docs, but the sources are still there -- they're
> still being built *if* you explicitly request it, and the nightly
> build must do that, since it's generating the on-line version that
> everyone sees.
> 
> 
>> I often program in an 'off line' manner, and I'd find on-line docs
>> to be way too slow. I don't mind building the docs once a day.
> 
> To make it easier to read, I'll make the punchline before I proceed to
> specify the details of why you won't have any problem.  The punchline
> is that your desire to use a local copy is in direct contradiction
> with the desire to get community involvement in improving the docs.
> No matter what facility is available for the community to discuss and
> supplement the docs -- if you have to go out of your way to see it,
> then you (the collective) just won't do it (statistically speaking).
> The best that you'd get is yet another scheme cookbook which will be
> left to accumulate binary dust, with very few people who read it, and
> very few of them who contribute to it.  My guess is that the
> percentages were 2% who read the cookbook -- and 2% of the readers
> contributed to it (and if I remember the rough numbers correctly, the
> numbers of people who contributed was indeed on the order of 0.01% of
> the number of users).
> 
> The main point is that if you want real community effort, then you
> need *almost everyone* to be aware of it -- both to get more people to
> read it, and to get more people to contribute to it.  This kind of
> interraction just cannot happen in batch mode, with changes getting
> through only on new releases, and worse, with participation only from
> a few enthusiastics who put in the extra effort to use this community
> site.  By making it the default you change the first 2% to 90% -- and
> the activity around these improvements is now done by 100-200 people
> instead of 4-5.
> 
> Back to your problem.  Here's how you and others can deal with "I want
> to read the docs off-line":
> 
> * A normal user (who wants the released version and nothing else)
>  downloads the docs, and from then on get to see only that.  The only
>  difference is explicitly asking for the docs to be installed
>  locally.
> 
> * A from-git user uses the the command-line flag to turn on building
>  the docs -- and then you get to use them locally just like the
>  above.
> 
> * Both users can download the new docs (with some menu entry or
>  something like that) from time to time -- the stable-release user
>  get updated docs without installing a new version, and the git user
>  get updated docs cheaply, with just a download instead of running
>  your own build.
> 
>  This is of course optional.  If the first user doesn't do it,
>  they're left with static unchanged docs -- just like now.  If the
>  second user doesn't do it, they need to continue paying cpu cycles
>  for building the docs -- just like now.
> 
> * Another option that would be available is "use the on-line docs if
>  they're accessible".  Then you'd get the local copy if you're not
>  on-line.
> 
> As for speed -- that will not be an issue.  By far, the biggest
> problem now is loading the JS index.  If the docs are on-line, then
> the search can happen on the server side.  This is another big
> benefit: the server side will be some racket code, therefore can do a
> proper search, including full-text, complicated queries and whatever
> you want.  You'll only pay for the network bandwidth.
> 
> Even better: *don't* do any searches -- no racket code, no apache
> proxying, no worrying about server load.  Instead -- use the google
> thing which was raised a short while ago.  We get the benefit of a
> company that makes a living out of doing good search.
> 
> [Obviously, the docs won't even need to live in the repo like the rest
> of the sources.  For a release-user-with-local-docs there's no
> difference since they only care about downloading a local copy, how it
> was built is irrelevant.  For a git-user-with-local-docs, this can be
> done in a similar way to svn externals -- with the docs repo being
> hooked in the normal repo (in collects/scribblings, for example), so
> you can still edit them with git.]
> 
> Eventually, I'd like to see the local docs option used less and less,
> so the focus can be on improving the on-line version.
> 
> -- 
>          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
>                    http://barzilay.org/                   Maze is Life!