Tools for managing a public 'library', handbook or FAQ, in markdown

Start of an investigation : May 2021 : mike hales Updated 2021 07 15
https://hackmd.io/OTUN2h5KQHuRz2JJBDEmCQ

Intention: To find a coherent and easily navigated way of posting a public 'library' for meet.coop (or a set of libraries, including private, ops-only libraries). Corresponds to the 'Library' category in the expanded trinity.

Why? Bcos it's simply not possible for anybody, right now, to get a comprehensive view of meet.coop . . contributions that members can make and ways members can engage one another, how to become a member and types of membership, the policies and development commitments of meet.coop, events & milestones planned and achieved, channels for member-enquiries or trouble reporting, etc etc.

This all needs wholesale, holistic redesign. And some kind of static, structured, one-stop front-end, rather than straggling, erratic forum threads and a limited website (limited for good reasons).

Conventionally this purpose might be handled in a wiki. (Then, with something like a push-newsletter or a pull-blog tacked on?). But the standard wiki interface (Mediawiki) may be both too complex, too uninteresting and too inflexible to serve our purpose. meet.coop abandoned its own wiki during its first year - why? Why did members think we could manage without one? Has the website met all the user-facing needs - no? Does the forum-plus-NextCloud-plus- Matrix/Element meet all the ops-members' needs - no?

Requirements for a public library/handbook/FAQ (or a private operational handbook):

  • Writeable in markdown
  • Wysiwyg editing
  • Uses the web as its (scrolling?) display space, not hard-copy (paged?) versions
  • Can be synchronously edited - like md docs in NextCloud
  • Presents the reader with a nested page structure - like a website - which is easily navigated. At least one level of nesting, preferably two, or three - all simultaneously viewable at filename or thumbnail level, in a hierarchical sidebar.
  • Very easily browsable by a reader, with simultaneous display of multiple pages (or thumbnails) and multiple levels/branches of document file hierarchy.
  • Writers can import other formats (Word? html?)
  • Accepts images easily and displays them well - This isn't great in NextCloud md docs.
  • Typography - plain but elegant. Custom fonts, logos, colours, for coop house-style?

Consider the following:

  • A book presentation - gitBook [alternatives]
  • A book or 'master-list' presentation - HackMD
  • A website presentation - Jekyll
  • Multiple MD documents in NextCloud public folders - The existing default for documantation.

A book presentation - gitBook

  • gitBook site - A 'knowledge base'
  • Who's using gitBook?
    • Hypha's gitBook - How do they feel about this - compared for example with docs held in NextCloud public folders? Are they gitBook fans?

Ouishare also uses the Mindmeister 'knowledge mapping', platform - just gussied-up mindmaps, not impressed, Loomio :), and Cobudget for allocation of finance, in 'buckets'.

  • gitBook alternatives
    • Outline - Looks very like gitBook
    • Read the Docs - Looks clean, is free-beer and free-libre; a hosted platform service. But is edited @ gitHub/gitLab
    • mkDocs support and mkDocs itself. Users guide. mkDocs is a static site generator running off markdown files, NOT a wysiwyg markdown editor - it's driven from the command line. Oh no!
    • continuation of original pre-commercial gitBook code- mdBook - Very nerdy and hands-on, interface lacks all sorts of affordances compared w gitBook. Not a good alternative for folks who are not programmers, working continually in git environments.

A book or 'master-list' presentation - HackMD

Note: this present page is a 'master-list'. Produced in HackMD.

  • HackMD website - "Real-time collaboration on documentation in markdown. Capture fleeting ideas and formalize tribal knowledge."
  • HackMD tutorial book - is this a gitBook? It looks just like one. Or is it a HackMD book? It probably is. Anyway, a HackMD 'book' looks as if it's functionally equivalent to a gitBook? ✔
  • The basic limitation of HackMD is, file management for docs. The web file management interface is klunky in the extreme, no hierarchical folder system, no nested display of a hierarchy with disclosure triangles - like in gitBook, for example. The file management is even worse than NextCloud - it's a flat structure and also takes up a lot of screen real-estate, with very large 'thumbnails' or 'tokens'. So, it's only when you're within a 'book', in HackMD, that you get a clean, easily navigable sidebar with nested file structure - which is fine, like gitBook. 👎
  • In contrast, gitBook is based on a file management regime (git) and immedaietely gives facilities for an organisation to have multiple 'spaces', and for books to be created within any of these spaces, but managed (eg searched) over the whole set of spaces belonging to the organisation. 👍
  • Limited import-export options - Includes DropBox cloud but not NextCloud, for example.
  • Limited download options - markdown/html/ODF but not pdf.
  • HackMD alternatives

A website presentation - Jekyll

  • As the basic 'FAQ' or library interface of a user-member with the entire product/operations/customer-service/payments/governance/events/forum community of meet.coop, what's the benefit of a website (managed thro Jekyll) vs a gitBook?
  • Is the answer different on different kinds of devices (eg phones)?
  • Is the answer basically a customisable 'skin', for glossiness purposes?
  • Parallel question (¿same question?), for ops members? Currently, do we think the NextCloud file system is the answer? Really?!
  • Jekyl website
  • Write in markdown ✔️
  • 'Blog-ready' - "Permalinks, categories, pages, posts, and custom layouts are all first-class citizens here.""
  • "You can easily deploy your site using GitHub for free" thro gitHub Pages - but who wants to be on gitHub?
  • Forestry - git-based content management repo for a Jekyll site
  • What do website authors feel about working thro Jekyll? Is is easy, is it a kludge?
  • This Jekyll regime does look kinda geeky - a domain for coders?; as might be expected, given the git-culture heritage 👎 When references to working from the command line start popping up, it's a sure sign of incipient geekness. Surely, something close to wysiwyg is best - like gitBook? Less flexibly powerful in formatting, and more like writing on pages with a typewriter. Keep it simple. Keep the contributing of pages open, to people with a wide range of skills.

MD documents in NextCloud public folders

  • Our status quo in meet.coop
  • Synchronous editing works pretty well. 👍
  • Via NextCloud app, it's possible to edit docs locally - and offline - in a specialist markdown editor. Makes a lot of difference to convenience? 👍
  • Each doc is an 'island'. No easily browsable linking across docs is available within a markdown document displayed in the NextCloud web interface - eg within 'books' or collections, via a navigation sidebar. In the web interface, to navigate systemically related docs, in a branched tree or semi-lattice, only the NextCloud one-level-at-a-time display of the file-system is available. Or embedded doc-to-doc explicit links, where one doc may be created to serve as a master-list (or directory or contents-list) for the whole collection. Klunky: very limiting of transparency and speed of browsing in a collection of docs.
  • For an owner-writer of docs, this can be made manageable by exploiting the NextCloud app, and editing synched copies of files on their own device (within a 'proper', nested-folder, file-management interface), in a local markdown editor. But for a reader, who must use the web interface, navigating from page-to-page or from folder-to-folder (ie from content-domain-to-content domain) within NextCloud is a pain in the arse. This simply won't bear comparison with an interface that has a proper, internal, nested-file-structure nav sidebar (plus maybe some high-level or frequently-used static categories displayed in a page header or footer); plus comprehensive <search>. 👎

Some general notes on UI

  • Actually . . two levels of sidebar is best: filenames first (nested, expandable), then thumbnails within the current folder (linear), and only then full page-display. Does any app offer this? This three-pane navigation set-up is now the default in many mail browsers for example; in my own markdown editor too.
  • Multiple-tab displays are ubiquitous, and essential - can be taken for granted for documents displayed in web browsers? This applies to all the above options, as browser-based options? But remember phone screens and small screens - next . .
  • Design justice- Beware: most folks have small screens. 13" laptops, or even phones. Don't assume that the luxurious screen real-estate of developers' desktop screens (and dual-screen setups) are any kind of norm. It's a pain being in a meeting with devs and admins, running around their big screens.

Approaches to documentation

Select a repo