# 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](http://learnstack.federated.wiki/view/welcome-visitors/view/digital-toolstack/view/extended-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**](https://www.gitbook.com/) - A 'knowledge base'
- - **what is** [gitBook](https://docs.gitbook.com/)
- - sign up for a [**free individual account**](https://app.gitbook.com/join) - open source projects get free accounts too.
- Who's **using** gitBook?
- - **Hypha**'s [gitBook](https://handbook.hypha.coop/) - How do they feel about this - compared for example with docs held in NextCloud public folders? Are they gitBook fans?
- - gitbook at [**OpenCollective**](https://docs.opencollective.com/help/)
- - **Ouishare**'s gitBooks. [Festival handbook](https://toolkit.ouisharefest.com/) - a toolkit & organisers' guide. Ouishare [handbook](https://handbook.ouishare.net/) - including governance & decision-making in a ['do-ocracy'](https://handbook.ouishare.net/governance-and-decision-making). Very sketchy handbook on [finances](https://finances.ouishare.net/).
>*Ouishare also uses the Mindmeister ['knowledge mapping', platform](https://www.mindmeister.com/pages/knowledge-mapping) - just gussied-up mindmaps, not impressed, Loomio :), and [Cobudget](https://cobudget.co/#/) for allocation of finance, in 'buckets'.*
- gitBook [alternatives](https://alternativeto.net/software/gitbook/)
- - [**Outline**](https://www.getoutline.com/) - Looks very like gitBook
- - [Read the Docs](https://docs.readthedocs.io/en/stable/) - Looks clean, is free-beer and free-libre; a hosted *platform service*. But is **edited @ gitHub/gitLab**
- - **mkDocs** [support](https://squidfunk.github.io/mkdocs-material/getting-started/) and [**mkDocs**](https://www.mkdocs.org/) itself. Users [**guide**](https://www.mkdocs.org/user-guide/writing-your-docs/). *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**](https://alternativeto.net/software/mdbook/about/) - 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.*
- - alternative in PhP - [**BookStack**](https://alternativeto.net/software/bookstack/about/)

### A book or 'master-list' presentation - HackMD
>Note: this present page is a 'master-list'. Produced in HackMD.
- HackMD [website](https://hackmd.io/) - "Real-time collaboration on documentation in markdown. Capture fleeting ideas and formalize tribal knowledge."
- HackMD **tutorial** [book](https://hackmd.io/c/tutorials/%2Fs%2Ftutorials) - 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](https://alternativetoapp.com/hackmd.html)

### 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**](https://jekyllrb.com/)
- 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](https://pages.github.com/) - but who wants to be on gitHub?
- Forestry - [git-based **content management repo**](https://forestry.io/) 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
- At MayFirst it's an issue [in their **forum**](https://comment.mayfirst.org/t/organizing-talks-about-approaches-to-documentation-organizar-charlas-sobre-estrategias-de-documentacion/2091)