Re: [9front] The 9 Documentation Project

[magma698hfsp273p9f@icebubble.org]

sirjofri+ml-9front@sirjofri.de writes:

> I thought about this some time and think we can do documentation
> better. Of course we have the very good fqa (which is 9front "only")
> and the official man pages as well as other documentation sources and
> guides. Most of these guides are distributed in various personal blogs
> and contribution to man pages and the fqa takes time (patch creation,
> review).

First, let me say that I think a "9 Documentation Project" is a great
idea.  Documentation is one of the places where Plan 9 (of all flavors,
including Inferno) is most lacking.  When I was first learning Linux, I
leaned heavily on the Linux Documentation Project (TLDP) and read many
of the "HOWTO"s in order to learn how Linux works and how to use it.
The Plan 9 family could benefit immensely from a similar body of
documentation.  s/TLDP/T9DP/ :)

> My dream is something like a publicly available wiki system (wikifs?)
> with good structure where every nine user can contribute to without
> review.

I would propose using a Web-accessible Wiki which manages changes using
a publicly-accessible git repository on the backend.  (Yes.  Here's
why.)

Some problems with Plan 9's wikifs:

  1.  The last time I tried using it via the Web, the Web interface
      didn't permit anyone to make edits.

  2.  Using wikifs requires acme, which means that a contributor must
      already have Plan 9 set-up and running and know how to use it.

  3.  It requires connection via 9p.  This means that Plan 9 must
      already be set-up, AND requires a live connection to the Internet.

  4.  It is hard to properly curate content and track your contributions
      on a Wiki when anything can be edited, by anyone, at any time.

  5.  It requires contributors to learn the Wiki mark-up language.
      That's not a huge hurdle, but requires source which is hard to
      read and annoying to maintain.

  6.  It is difficult to maintain cross-references between pages on a
      Wiki.  When pages are renamed, when pages are consolidated, or
      when information is relocated from one page to another, references
      to those pages need to be updated.

  7.  When I tried to use Wikifs from acme, about half the time, it
      didn't work.  I'd keep receiving error messages that the other end
      "hung-up" on me.

Some advantages of using a git-backed Wiki:

  A.  It would be accessible via the Web, which makes it accessible to
      most people, whether they are on Plan 9 or another device; whether
      they are just learning how to use Plan 9 or are a seasoned user
      who just needs to look something up; and whether they are
      correcting a simple typo or contributing an entirely new article.

  B.  It provides a place to centralize things like /sys/doc, /man, the
      FQA, and Wiki pages (possibly on separate branches).  When
      spinning a new release of the OS, it'd be a simple matter to
      pull-in all the latest changes.

  C.  It provides a way for contributors to curate, or take ownership,
      of their own content and contributions.  By maintaining their own
      branch, users can keep track of their contributions, vet changes
      made by others, and accept the edits/improvements of which they
      approve.  (Changes to the default branch, of course, could be made
      by anyone, whether using git or the Web interface.)  This removes
      the need for a single "gatekeeper" to approve changes.

  D.  DVCS like git already have well-understood mechanisms for tracking
      when files get renamed.  When someone follows a link to a page
      which has been renamed, the Wiki can find the new name of the page
      and issue an HTTP 304 redirect.

  E.  Because Plan 9, including its documentation, is so heavily
      text-based, the problem of cross-referencing pages becomes easier
      to solve.  Text-based automated tools can scan the documentation,
      flagging and/or fixing-up cross references.

  F.  git would make it easy to check-out the latest version of (some or
      all of) the docs, or do a full clone of the repo to get all the
      revisions on all the branches.

  G.  Power users are often frustrated by having to "point, click, type,
      scroll, repeat" as is often required by Web interfaces.  Using
      git, a power user could just make a change using a text editor,
      and commit from the command line, without even having to touch a
      Web browser.

  H.  git solves the problem of off-line use.  Documentation checked-out
      from the repo can be read entirely off-line, and changes that are
      made off-line can be committed whenever an Internet connection
      becomes available.

  I.  Historical versions of documentation can be archived, providing a
      sort of "time machine" for the documentation.

  J.  A branch (or a separate repo) could be used to archive the 9front
      mailing list, keep logs of discussion on the IRC channel, etc.

  K.  Because the documentation is almost entirely text, one could
      "grep" all the docs (and/or the mailing list, IRC channel, etc.)
      for answers, in a single place, before asking a question.  The
      grep/search could be entirely off-line, without having to rely on
      a Web search engine to find relevant information.  (Of course, any
      base64-encoded e-mail messages would have to be converted to
      UTF-8, but that's easy.)

  L.  A branch (or separate repo) could even be used as an informal bug
      tracker.  Issues could be added, and commented upon, etc. either
      from the Web interface, or from git.

Because much of the work done by a Wiki (tracking changes) is already
done by git, it shouldn't be too difficult to write a git-backed Wiki.
In fact, it's likely that one or more implementations already exist.  In
order to use one of these for "T9DP", it would just need to be ported to
Plan 9 (ideally, by translating it into Limbo).  Because Inferno has a
Limbo compiler that runs on Plan 9, the Wiki server would be able to
compile and run on any 9 variant: 9front, Inferno, etc.