From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-pf1-f174.google.com ([209.85.210.174]) by ewsd; Wed Jul 29 23:12:42 EDT 2020 Received: by mail-pf1-f174.google.com with SMTP id u185so14233853pfu.1 for <9front@9front.org>; Wed, 29 Jul 2020 20:12:37 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=from:content-transfer-encoding:mime-version:subject:date:references :to:in-reply-to:message-id; bh=8nuXthzNN+WKWOn4wCbGdj7J+2RxR2Rr7V+JRieW+7w=; b=asNyOjPWZTadSEfXa4iooye+jRqa29j+5LICLywZcE8HAaPD1Cte5C7wpBjyqHxe/5 VjclpkhOD+hLS2V/6O6g7RSJcckJ2eB74nKV9jw1SYPZ/zAEI+udnO+bIY5ByGmM4QQN FkhR+i03IBP8Ux4dXZMtUYQmHE3CyWMC/tPesP7PiBKc9vxeozHLWUxU/OhiMKE6WdSF tINnZaCRrxTYDKKLnemJUVHDvhRAiJLxS624g4P1gfIhSXUc9V5OgRhFQ7x4S2C30iMS dbII4FZbCIhdUuZ7TvwATK5L6cAnF3fSrf0fmxjTVUMFlaehnMDxjaRlW+of9DPGoQq0 QbQw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:date:references:to:in-reply-to:message-id; bh=8nuXthzNN+WKWOn4wCbGdj7J+2RxR2Rr7V+JRieW+7w=; b=sPL2QQ7lFDGUkNF7TWYik4bBxW15t5fbTdQzkaZqtEERMdONwu+PYezLVhHgvrAXyT i+hvgGHijA751a38oRwzjAAW1ahRM4YvGGBK3AZnMchmKoyaN+BOi6YzIvMEy6XcHub7 Fc+gMvuirUoEidGF2iDK8K3sOgFLXhW670wh4IJAuJf2i+jmxwyRTLBIk9J0Z4BQm113 +f2kU6ov5ngoOLujTJy+9qS+ijv9M5OCmBDUrnSpr8foCozFIgS2oawUXd6ym/h7qJeY iYKV6Mo5YWrmmQh/Li4qCqlHHgv/QBHnKGYgaeSWM2FChsDHbAVmFgj7ABmnhp1I6VrQ ZGVQ== X-Gm-Message-State: AOAM5303GXJOJAO2Jk6R3WK5ivt2XYSZpaWGLvCnM1BqA6Y8CKujr/Bc KKb+KPaBGUzLzET8wOYQdHVnIEcod8s= X-Google-Smtp-Source: ABdhPJwQBdauDfWDbRo9aRGTr3K61lbKkY+pWjwYw2nMjvXczm7IQ2tTK9aMtPu7VE/TiFo8Ef9NhQ== X-Received: by 2002:a63:4956:: with SMTP id y22mr32383773pgk.380.1596078756484; Wed, 29 Jul 2020 20:12:36 -0700 (PDT) Return-Path: Received: from halfwits-mbp.lan ([104.246.165.139]) by smtp.gmail.com with ESMTPSA id y4sm3917263pff.44.2020.07.29.20.12.35 for <9front@9front.org> (version=TLS1_2 cipher=ECDHE-ECDSA-AES128-GCM-SHA256 bits=128/128); Wed, 29 Jul 2020 20:12:36 -0700 (PDT) From: Michael Misch X-Google-Original-From: Michael Misch Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable Mime-Version: 1.0 (Mac OS X Mail 13.4 \(3608.80.23.2.2\)) Subject: Re: [9front] The 9 Documentation Project Date: Wed, 29 Jul 2020 20:12:34 -0700 References: <2EB629ED-9DB8-441F-9786-A9519930E128@stanleylieber.com> To: 9front@9front.org In-Reply-To: <2EB629ED-9DB8-441F-9786-A9519930E128@stanleylieber.com> Message-Id: <6D3C8A0C-139F-4B3C-817D-619AB1E2B16B@gmail.com> X-Mailer: Apple Mail (2.3608.80.23.2.2) List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: generic RESTful property shader SVG over WEB2.0 realtime cloud 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 = wrote: >=20 > On July 29, 2020 10:14:23 PM EDT, ori@eigenstate.org wrote: >>=20 >>>> 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. >>>=20 >>> fqa7 needs help. >>=20 >> What in particular do you want help with? >>=20 >>>> "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. >>>=20 >>> i agree we need something like this. i've dabbled with every piece >>> except assembling a narrative. >>=20 >> I think there are a few different kinds of docs that are >> worth having. >>=20 >> I mentioned some of this on gridchat, but I'll repeat i >> here for posteriority. >>=20 >> - Reference manuals. Covering all the options that a >> program has, as well as describing what it does. >> This is covered by our manpages. >>=20 >> - 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. >>=20 >> - 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. >>=20 >> - Cheat sheets: Quick references and summaries of how >> to do things. The FQA, basically. >>=20 >> 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). >>=20 >> 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. >>=20 >> 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. >>=20 >> 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. >=20 > 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. >=20 > 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. >=20 > 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? >=20 > you know, i never asked permission to create the fqa, either. in point = of fact we never asked permission to create 9front. >=20 > nobody can stop you but yourself. >=20 > sl