Re: [9front] The 9 Documentation Project

["Ethan Gardener" <eekee57@fastmail.fm>]

On Thu, Jul 30, 2020, at 8:15 PM, Kurt H Maier wrote:
> 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.

yeah, we don't need another labour sink.

> >   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?

i considered contributions from users struggling to set up, but honestly, those contributions should go to mailing list or bug tracker. they can later be condensed for the wiki by the user or others. this has worked with the fqa, if i remember right.

> >   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. 

doesn't wikifs track who last edited the file? some plan 9 filesystems do.

> >   I.  Historical versions of documentation can be archived, providing a
> >       sort of "time machine" for the documentation.
> 
> This is what yesterday(1) is for.

i cautiously agree. yesterday won't catch multiple changes to the same file in the same day. how many manic monkeys are going to be working on this? speaking of manic monkeys... when i edit wikis, i generally find myself wishing all my changes to a page on a given day would appear as a single commit. there are times when i want the opposite. i don't think any wiki allows for both, not even those with a 'minor edit' flag.

> >   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"

EVIL!!! lol

my primary opinion on all of this is: if you have a good tool, use it and stop requiring users to learn other junk. on the other hand, 9front itself uses hg because users were dissatisfied with the lack of commit messages. this also applies to wikis to some extent. i don't see the problem for wikis; summaries are nice, but diffs are more useful. 

remember that you can grep or diff wikifs without having to resort to $scm's special tools *or* addressing history in a tool-specific way. i dare to say the most loved facet of plan 9 is that the system is unified and fairly clean. is polluting it with scms worth the cost?

i'm not going to argue this point further because frankly, parts of plan 9 are already not unified and clean. my development efforts are now going into an experiment to see if better tools are possible.

> >   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.

indeed! this point looks like a case of techie brain failure syndrome, a horribly common problem plan 9 was thankfully largely free of. i think it's to do with trying to cram too much into the working memory; there's a limit to what it can hold. just like multi-tasking, it makes you feel good, but that's just because you're getting high off your own neurochemicals. you're actually *less* capable when you try too hard.

you know, the above point may be directly applicable to using scms with their arcane things to remember on top of the code you're writing. however, it's definitely directly applicable to coming up with analysis scripts for dump or wikifs. (despite plan 9's lovely unified regexps.) which is the lesser evil? don't ask me, i'm trying to develop something better than either. :}

> > 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.

indeed. and speaking from experience, things written in limbo do not fit into plan 9 any better than things written in posix c.

now, i'd better get brunch and stop getting high off my own neurochemicals from just trying to understand this overthought mess. last comment: i think it's very well worth listening to khm & sl, they have practical experience.

> 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
>