From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from icebubble.org ([174.136.103.210]) by ewsd; Thu Jul 30 14:22:54 EDT 2020 Received: from petunia by icebubble.org with local-bsmtp (Exim 4.76) (envelope-from ) id 1k1DEf-0000gJ-5J for 9front@9front.org; Thu, 30 Jul 2020 18:24:57 +0000 Received: from rusat by cmarib.ramside with local (Exim 4.72) (envelope-from ) id 1k1D35-0004gI-Uz for 9front@9front.org; Thu, 30 Jul 2020 18:13:00 +0000 From: magma698hfsp273p9f@icebubble.org To: 9front@9front.org Subject: Re: [9front] The 9 Documentation Project References: Date: Thu, 30 Jul 2020 18:12:59 +0000 In-Reply-To: (sirjofri's message of "Mon, 27 Jul 2020 09:09:44 +0000 (UTC)") Message-ID: <86tuxoq3bo.fsf@cmarib.ramside> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii List-ID: <9front.9front.org> List-Help: X-Glyph: ➈ X-Bullshit: session callback controller sirjofri+ml-9front@sirjofri.de writes: > I thought about this some time and think we can do documentation > better. Of course we have the very good fqa (which is 9front "only") > and the official man pages as well as other documentation sources and > guides. Most of these guides are distributed in various personal blogs > and contribution to man pages and the fqa takes time (patch creation, > review). First, let me say that I think a "9 Documentation Project" is a great idea. Documentation is one of the places where Plan 9 (of all flavors, including Inferno) is most lacking. When I was first learning Linux, I leaned heavily on the Linux Documentation Project (TLDP) and read many of the "HOWTO"s in order to learn how Linux works and how to use it. The Plan 9 family could benefit immensely from a similar body of documentation. s/TLDP/T9DP/ :) > My dream is something like a publicly available wiki system (wikifs?) > with good structure where every nine user can contribute to without > review. I would propose using a Web-accessible Wiki which manages changes using a publicly-accessible git repository on the backend. (Yes. Here's why.) 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. 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. 3. It requires connection via 9p. This means that Plan 9 must already be set-up, AND requires a live connection to the Internet. 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. 5. It requires contributors to learn the Wiki mark-up language. That's not a huge hurdle, but requires source which is hard to read and annoying to maintain. 6. It is difficult to maintain cross-references between pages on a Wiki. When pages are renamed, when pages are consolidated, or when information is relocated from one page to another, references to those pages need to be updated. 7. When I tried to use Wikifs from acme, about half the time, it didn't work. I'd keep receiving error messages that the other end "hung-up" on me. Some advantages of using a git-backed Wiki: A. It would be accessible via the Web, which makes it accessible to most people, whether they are on Plan 9 or another device; whether they are just learning how to use Plan 9 or are a seasoned user who just needs to look something up; and whether they are correcting a simple typo or contributing an entirely new article. B. It provides a place to centralize things like /sys/doc, /man, the FQA, and Wiki pages (possibly on separate branches). When spinning a new release of the OS, it'd be a simple matter to pull-in all the latest changes. C. It provides a way for contributors to curate, or take ownership, of their own content and contributions. By maintaining their own branch, users can keep track of their contributions, vet changes made by others, and accept the edits/improvements of which they approve. (Changes to the default branch, of course, could be made by anyone, whether using git or the Web interface.) This removes the need for a single "gatekeeper" to approve changes. D. DVCS like git already have well-understood mechanisms for tracking when files get renamed. When someone follows a link to a page which has been renamed, the Wiki can find the new name of the page and issue an HTTP 304 redirect. E. Because Plan 9, including its documentation, is so heavily text-based, the problem of cross-referencing pages becomes easier to solve. Text-based automated tools can scan the documentation, flagging and/or fixing-up cross references. F. git would make it easy to check-out the latest version of (some or all of) the docs, or do a full clone of the repo to get all the revisions on all the branches. G. Power users are often frustrated by having to "point, click, type, scroll, repeat" as is often required by Web interfaces. Using git, a power user could just make a change using a text editor, and commit from the command line, without even having to touch a Web browser. H. git solves the problem of off-line use. Documentation checked-out from the repo can be read entirely off-line, and changes that are made off-line can be committed whenever an Internet connection becomes available. I. Historical versions of documentation can be archived, providing a sort of "time machine" for the documentation. 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. 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.) L. A branch (or separate repo) could even be used as an informal bug tracker. Issues could be added, and commented upon, etc. either from the Web interface, or from git. 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.