Re: [9front] The 9 Documentation Project

[Michael Misch <michaelmisch1985@gmail.com>]

I have no weight nor should you care about my opinion, but what sl just posted was a breath of fresh air

> On Jul 29, 2020, at 8:06 PM, Stanley Lieber <sl@stanleylieber.com> wrote:
> 
> On July 29, 2020 10:14:23 PM EDT, ori@eigenstate.org wrote:
>> 
>>>> 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.
> 
> all common complaints are centered on the material covered in fqa7. nobody understands how it all fits together, and we don't attempt to tell them. that seems to be the main problem we're stumbling over here. i agree, it sucks.
> 
> somebody just needs to start writing documents. i don't think any further bureaucracy is required. aside from khm's points that i highlighted above, i really think all the rest is satisfied by, essentially, a central wiki-like-thing of some sort. failing the spontaneous self-organization of an acceptably egalitarian central government, i am happy to link to any extant source of documentation on the fqa. problem solved? and yes, patches to the fqa are always welcome. i may be misremembering, but i don't think i have rejected any pacthes that were sent to me.
> 
> one last point i want to highlight before i throw my phone in the lake: there is some overlap here between calls for a simplified overview document, and a larger, basic disagreement with the style and sensibility in which plan 9 documentation has traditionally been presented. i do think these are separate issues. we do need an overview document. we don't need to cede authority over what ships on the iso to random customers. and really, there is no reason why community documentation needs to be presented under an "official" 9front banner anyway. why is this a sticking point? more than one community wiki already exists. as has been pointed out several times, nobody posts to these things (exceptions duly noted). that's why we don't emphasize them anymore. just create your own documents and make them available. tell me, and i will make sure the fqa points to them. it really is that simple. the way some of this keeps getting revisited makes it seem like  folks are getting very hung up over what is and isn't considered official 9front business. but, why does it matter?
> 
> you know, i never asked permission to create the fqa, either. in point of fact we never asked permission to create 9front.
> 
> nobody can stop you but yourself.
> 
> sl