From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from wopr.sciops.net ([216.126.196.60]) by ewsd; Mon Jul 27 18:47:52 EDT 2020 Received: (qmail 64027 invoked by uid 1001); 27 Jul 2020 15:47:44 -0700 Date: Mon, 27 Jul 2020 15:47:44 -0700 From: Kurt H Maier To: 9front@9front.org Subject: Re: [9front] The 9 Documentation Project Message-ID: <20200727224744.GA61790@wopr> Mail-Followup-To: 9front@9front.org References: <5F940CDA-1E2D-4ACE-B70D-AAAD0638C77A@stanleylieber.com> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <5F940CDA-1E2D-4ACE-B70D-AAAD0638C77A@stanleylieber.com> List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: virtual object-oriented information base On Mon, Jul 27, 2020 at 06:17:41PM -0400, Stanley Lieber wrote: > > yes. i wasn't arguing that we don't need more and better documentation. we always do. > > my experience with this struggle over the past ten years has been that nobody ever helps. everyone has good ideas, but nobody ever helps. see also: bug tracker. > > perhaps ironically, the parts of the fqa that people complain about the most are the few parts held over from the old google code wiki. > > i strongly support a public wiki. > Everybody always talks about the weather, but nobody does anything about it. 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 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. 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. khm