Re: [9front] The 9 Documentation Project

[ori@eigenstate.org]

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

What in particular do you want help with?

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

I think there are a few different kinds of docs that are
worth having.

I mentioned some of this on gridchat, but I'll repeat i
here for posteriority.

- Reference manuals. Covering all the options that a
  program has, as well as describing what it does.
  This is covered by our manpages.

- Theory of operation documents. These should give an
  overview of how the parts of the system fit together,
  and the design considerations that went into it.
  We've got hints of this in /sys/doc, but it's spotty.

- Tutorials. Hand holding on how to get tasks accomplshed
  end to end, in detail, explaining both steps and how
  to do things. This is mostly notes scattered over
  the web.

- Cheat sheets: Quick references and summaries of how
  to do things. The FQA, basically.

The divisions are fuzzy -- the synopsis and examples
of manpages, for example, also act as a cheat sheet
if you already know what you're looking for. But some
duplication is fine (and, in fact, good).

As far as most projects go, we're actually in really good
shape -- compare to, say, kubernetes, which is basically
just a bucket of half-assed examples.

The biggest gaps I see are around some theory of operation
documents, as well as some tutorials. I keep referring to
/sys/doc/comp.ps as an example of what I'd like, so here's
one more mention of it.

And, of course, if people want to look over the manpages
and fqa, and submit patches for those: while they're
pretty good, that would also be welcome.