From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from wopr.sciops.net ([216.126.196.60]) by ewsd; Thu Jul 30 15:15:28 EDT 2020 Received: (qmail 54713 invoked by uid 1001); 30 Jul 2020 12:15:22 -0700 Date: Thu, 30 Jul 2020 12:15:22 -0700 From: Kurt H Maier To: 9front@9front.org Subject: Re: [9front] The 9 Documentation Project Message-ID: <20200730191522.GA52500@wopr> Mail-Followup-To: 9front@9front.org References: <86tuxoq3bo.fsf@cmarib.ramside> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <86tuxoq3bo.fsf@cmarib.ramside> List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: proven XML over SSL module table On Thu, Jul 30, 2020 at 06:12:59PM +0000, magma698hfsp273p9f@icebubble.org wrote: > Some problems with Plan 9's wikifs: > > 1. The last time I tried using it via the Web, the Web interface > didn't permit anyone to make edits. Any wiki is a high-profile spam target. Mitigating that spam is labor-intensive. Be prepared to deal with this. > 2. Using wikifs requires acme, which means that a contributor must > already have Plan 9 set-up and running and know how to use it. As much as I dislike acme, plan9port acme supports this. But on a larger note, why do we need documentation contributions from people who are not using the system? Surely other support channels would be more appropriate? > 4. It is hard to properly curate content and track your contributions > on a Wiki when anything can be edited, by anyone, at any time. This objection seems to be in conflict with the objections about how hard it is to accept contributions from anyone on any platform. > I. Historical versions of documentation can be archived, providing a > sort of "time machine" for the documentation. This is what yesterday(1) is for. > J. A branch (or a separate repo) could be used to archive the 9front > mailing list, keep logs of discussion on the IRC channel, etc. Now we've moved from "I want a wiki whose source is in a dvcs" to "we should just stop using fileservers" > K. Because the documentation is almost entirely text, one could > "grep" all the docs (and/or the mailing list, IRC channel, etc.) > for answers, in a single place, before asking a question. The > grep/search could be entirely off-line, without having to rely on > a Web search engine to find relevant information. (Of course, any > base64-encoded e-mail messages would have to be converted to > UTF-8, but that's easy.) This is already the case by mounting the wiki and copying it to your computer. > Because much of the work done by a Wiki (tracking changes) is already > done by git, it shouldn't be too difficult to write a git-backed Wiki. > In fact, it's likely that one or more implementations already exist. In > order to use one of these for "T9DP", it would just need to be ported to > Plan 9 (ideally, by translating it into Limbo). Because Inferno has a > Limbo compiler that runs on Plan 9, the Wiki server would be able to > compile and run on any 9 variant: 9front, Inferno, etc. There are about sixteen thousand dvcs-backed wiki programs; many of them already work on Plan 9. None of them are written in Limbo, though. I don't like the idea of abandoning 9p in favor of git (or any other dvcs, for that matter). However, if someone puts up a wiki, let's migrate the data from code.9front.org/wiki to it and I'll set up a redirect. In my opinion, wikis in general are trash piles where information goes to die. The defining feature of a wiki, inter-document linking, is fragile, almost entirely useless, and labor-intensive to maintain. Tracking changes is a red herring; the wiki itself doesn't even need to do this. What it DOES need to do is process every document, either at commit time or at render time, looking for carefully-crafted tokens, figuring out whether the corresponding document exists, and generating relevant hyperlinks in the output. The only circumstances under which this provides value involve a phenomenally large userbase who is extremely active. Instead I recommend using whatever storage you like (9p server, dvcs, dvcs ON a 9p server, whatever) and then setting up an automated pipeline to generate HTML output, which you then serve. Your bespoke Limbo program then becomes much simpler: it just needs to let a given spammer edit the source document. This is a much simpler and lower-resource-requirement task than implementing a wiki, with all of its useless WikiLinks document-parsing rabbit holes. This is in fact how werc wikis work. Nobody's expanded werc's wiki software to be dvcs-backed because the filesystem is expected to be useful. However, given that the werc wiki, dirdir, is forty lines of rc, I'd bet it would be pretty easy to do. The above text is based on having spent a lot of time and effort hosting similar software as part of similar endeavors over the years. I will not be offended if it is ignored. When consensus is reached and Documentation Valhalla is made real I'll happily redirect to it and experience a real sense of joy as I turn off the old wiki. khm