Re: [9front] The 9 Documentation Project

[sl@stanleylieber.com]

> 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 have to apologize because 1.) i forgot this was even there, and 2.)
i didn't know people had added anything to it, at all.


> 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.

fqa7 needs help.


> 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.

i agree we need something like this. i've dabbled with every piece
except assembling a narrative.

sl