Documentation update

[barneycarroll]

The switch from Gitter to Zulip mandates a documentation update. On the most basic level, this merely requires updating the ‘Chat’ link in top-level navigation. But the change of circumstance stimulates concerns about Mithrils overall vagueness in public relations, holistic documentation on the official site being a critical aspect of this.

Currently the documentation has a top level division of Guide | API | Chat | GitHub. The latter two link directly to external services, while the former are internal links to holistic on-site documentation with subsections. One of the last subsections of the Guide is Social: I feel the content there needs extracting & extending to a higher level to explain what is and what isn't on the site; how to read documentation, what other sources there are and how to use them.

Mithrils public space is currently disparate & ambiguous; overly officious & platform-specific in places, out-of-date & vague in others. Various services have different ambiguous inter-related functions, and it's left to visitors to determine what goes on where and what the significance is.

The move to Zulip presents an opportunity to cull & consolidate. Chat & Github are essential resources but we ought to explain why and wherefore, and simultaneously remove some stuff.

Zulip allows restructurable threading which suits our historical strength & dependence on open & organic chat. I therefore suggest we consolidate conversational function there and remove Github Discussion & Wiki: semi-permanent information ought to be encoded either in the Guide section of documentation for canonical advice or atomic contributions to @orbitbot Awesome Mithril in the case of non-canonical literature.

I personally dislike the bureaucratically laborious and officious issue templates & labelling, but I recognise this is a somewhat personal style preference and the stickling gate-keeping can have its uses. At the same time, Claudia has relinquished duties & authority from her longstanding position of executive administration so we may consider that her legitimate determining voice for maintaining a huge amount of work in accordance with personal administrative preferences is somewhat lessened, and a less formalised injunction to bureaucracy might suit us going forward. With this in mind in the immediate term I recommend removing the formal instructions for GitHub in the documentation (currently under Guide > Social > Contributing) — seeing as any attempted engagement with GitHub will present users with those injunctions, we ought to remove those specifics from the docs proper and instead describe the general function of GitHub in the same breath as we do Zulip, Awesome Mithril, the Twitter account, the StackOverflow tag.

Finally, the job postings section ought to be abolished. It's a silly idea to have this as a prominent element of documentation considering such things are temporary, fleeting, and not a canonical piece of information.