Re: [9front] The 9 Documentation Project

[Kurt H Maier <khm@sciops.net>]

On Mon, Jul 27, 2020 at 06:17:41PM -0400, Stanley Lieber wrote:
> 
> yes. i wasn't arguing that we don't need more and better documentation. we always do.
> 
> my experience with this struggle over the past ten years has been that nobody ever helps. everyone has good ideas, but nobody ever helps. see also: bug tracker.
> 
> perhaps ironically, the parts of the fqa that people complain about the most are the few parts held over from the old google code wiki.
> 
> i strongly support a public wiki.
> 

Everybody always talks about the weather, but nobody does anything about
it.

I put up code.9front.org/wiki mostly so we can demonstrate that large
swaths of time go by with no changes, and the changes that show up are
generally from a handful of people.  I don't really like wikis as
documentation and/or knowledge bases because they only work when a
preponderance of users contribute.  I would much prefer thet see
specific sections of the FQA overhauled in a thoughtful manner, but I
sure do not have free time for that at the moment.

The problem with the current introductory garden path is that each piece
of advice reults in roadblocks to future pieces of advice, e.g. "set up
a terminal that can accept cpu connections, now set up these services on
another machine, now tear down step one and rebuild it in step two's
image" etc.  It works for "zero to running" but it sucks as a
pedagogical approach, as not all learners do well with the "draw the
rest of the fucking owl" approach.

Old electronics manuals (specifically, here thinking of Textronics
oscilloscope manuals) used to have a section entitled "Theory of
Operation" which went over at a high level what each component and/or
panel button did and why, culminating in an explanation of how they
worked together in common scenarios.  Such a document explaining what
these services (ndb, factotum, secstore, rpcu, etc) do without getting
distracted by administration instructions may be a valuable document.

"What does this tool do and when do I use it" is a fundamentally
different question than "how do I operate this tool" and I think mixing
them in the FQA may be doing a disservice to some segment of the
readership.  I personally prefer the mixed approach, but I'm not
everyone.  Yet.

khm