From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from 107.207.65.229 ([107.207.65.229]) by ewsd; Wed Jul 29 23:06:50 EDT 2020 Date: Wed, 29 Jul 2020 23:06:43 -0400 In-Reply-To: References: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [9front] The 9 Documentation Project To: 9front@9front.org From: Stanley Lieber Message-ID: <2EB629ED-9DB8-441F-9786-A9519930E128@stanleylieber.com> List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: storage hypervisor-oriented configuration-oriented hardware On July 29, 2020 10:14:23 PM EDT, ori@eigenstate=2Eorg 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=2E >>=20 >> fqa7 needs help=2E > >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=2E I personally prefer the mixed approach, but I'm not >>> everyone=2E Yet=2E >>=20 >> i agree we need something like this=2E i've dabbled with every piece >> except assembling a narrative=2E > >I think there are a few different kinds of docs that are >worth having=2E > >I mentioned some of this on gridchat, but I'll repeat i >here for posteriority=2E > >- Reference manuals=2E Covering all the options that a > program has, as well as describing what it does=2E > This is covered by our manpages=2E > >- Theory of operation documents=2E These should give an > overview of how the parts of the system fit together, > and the design considerations that went into it=2E > We've got hints of this in /sys/doc, but it's spotty=2E > >- Tutorials=2E Hand holding on how to get tasks accomplshed > end to end, in detail, explaining both steps and how > to do things=2E This is mostly notes scattered over > the web=2E > >- Cheat sheets: Quick references and summaries of how > to do things=2E The FQA, basically=2E > >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=2E But some >duplication is fine (and, in fact, good)=2E > >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=2E > >The biggest gaps I see are around some theory of operation >documents, as well as some tutorials=2E I keep referring to >/sys/doc/comp=2Eps as an example of what I'd like, so here's >one more mention of it=2E > >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=2E all common complaints are centered on the material covered in fqa7=2E nobo= dy understands how it all fits together, and we don't attempt to tell them= =2E that seems to be the main problem we're stumbling over here=2E i agree,= it sucks=2E somebody just needs to start writing documents=2E i don't think any furthe= r bureaucracy is required=2E aside from khm's points that i highlighted abo= ve, i really think all the rest is satisfied by, essentially, a central wik= i-like-thing of some sort=2E failing the spontaneous self-organization of a= n acceptably egalitarian central government, i am happy to link to any exta= nt source of documentation on the fqa=2E problem solved? and yes, patches t= o the fqa are always welcome=2E i may be misremembering, but i don't think = i have rejected any pacthes that were sent to me=2E one last point i want to highlight before i throw my phone in the lake: th= ere is some overlap here between calls for a simplified overview document, = and a larger, basic disagreement with the style and sensibility in which pl= an 9 documentation has traditionally been presented=2E i do think these are= separate issues=2E we do need an overview document=2E we don't need to ced= e authority over what ships on the iso to random customers=2E and really, t= here is no reason why community documentation needs to be presented under a= n "official" 9front banner anyway=2E why is this a sticking point? more tha= n one community wiki already exists=2E as has been pointed out several time= s, nobody posts to these things (exceptions duly noted)=2E that's why we do= n't emphasize them anymore=2E just create your own documents and make them = available=2E tell me, and i will make sure the fqa points to them=2E it rea= lly is that simple=2E the way some of this keeps getting revisited makes it= seem like folks are getting very hung up over what is and isn't considere= d official 9front business=2E but, why does it matter? you know, i never asked permission to create the fqa, either=2E in point o= f fact we never asked permission to create 9front=2E nobody can stop you but yourself=2E sl