Adopting Bookstack as our Wiki

Person or group submitting

p

Proposal History

Motivation

To reduce friction in the creation and retrieval of Basement documentation to the benefit of new and old members alike.

Proposal overview

I propose moving from our current Hedgedoc as our wiki to our existing Bookstack instance.

Details

Background info

The basement has been using Hedgedoc as an improvised wiki since 2022. The recommendation for Hedgedoc was taken from the hackerspace.zone suite of self-hosted software. Hedgedoc is designed to be and works well as a collaborative markdown editor, but we then attempted to build an entire wiki on top of it. 

These are the biggest problems with using Hedgedoc as a wiki:

• There is no inherent structure to the collection of documents. All the markdown files live in a single flat folder. If the user clicks the "New Page" button a new file with a name like Untitled-149.md is created. The only structure that exists comes from links from one page to another, so pages are easily orphaned. While this could work for running a website on Hegedoc, this seems like a bad match for the wiki usecase which should be accommodating to newer members who are willing to contribute documentation to the project.
• There is no indexing or search. Information retrieval is extremely arduous in our current setup and it hides away the majority of our corpus of documentation.

Bookstack (a fully-featured wiki software) solves these problems by including search as a feature, and enforcing an information hierarchy of Shelves, Books, Chapters (optional) and Pages. These metaphors would appear to be easily grokable by less technically savvy users, and so far I have found them adequate for organizing documentation.

Additionally, Bookstack has a WYSIWYG editor while also allowing the user to switch to editing the raw markdown. This is more accommodating to less techie users while allowing seasoned hackers to keep writing markdown if they want.

Groups this affects

The Basement Group

Work required

• migrating existing documentation to the new system (Bookstack has a rest api that should hopefully make this a bit less tedious)
• changing our habits to take meeting notes etc in the new wiki

work that was already completed towards this effort:

• micro installed Bookstack on the server in September 2023
• lp conducted a thorough survey of the wiki software landscape in 2024 and concluded that bookstack was the most usable
• p fixed permissions issues and prototyped a structure for
  

Individual or group doing labor

I (p) am willing to do the data migration. 

Money required

This does not cost any additional money to implement, but does depend on the digital ocean droplet that runs our self-hosted stack which I believe costs around $80/mo.

Proposals

I propose moving from using our current Hedgedoc as our wiki to our existing Bookstack instance. Both systems are up and running, so implementing this proposal consists of changing our habits in generating new documentation as well as migrating existing documentation to the new platform. While it might be a bit of work to migrate the historic contents I believe the effort will be worth it even solely for the indexing and search features in the new platform.

This proposal does not say anything about what to do with the existing Hedgedoc instance itself. It's likely still useful in  a google doc / cryptpad role.

Comments