Proposals

• Consensus Model
• Adopting Bookstack as our Wiki

Consensus Model

Consensus model (WIP draft)

This is a proposal for a Temporary consensus model. The idea would be to use it for the time being, and if passed, in 6 months review our experience with it and decide if we want to continue using it

(from jonah: this is simply a basic implementation of the consensus model/rules from 'consensus' by Peter Gelderloos thank you P for the rec - the things I have added/specified are the 2 meetings to vote rule, and the 3 votes to pass minimum aka a quorum)

• proposals must appear in a written form
  • Anybody has the right to make a proposal (even people without voting rights [on voting rights, see section ... below]).
  • The person who makes a proposal is its sponsor. A proposal must have one sponsor, and may have more than one sponsor.
  • proposals must be added to the agenda before the meeting
• The sponsor will give a live introduction to the proposal, which provides an opportunity for the sponsor to add context and open further discussion.
• only the sponsor has the unilateral right to withdraw a proposal before the voting period is completed.
• anyone can bring a proposal, and they must explain their proposal in person. The proposal must have a concrete ‘pass or fail’ action. An example of a good proposal:
  • “I propose that we build a dust shield around the wood shop, made of plexiglass sheets and screws, using existing money in our budget. me and my friend patricia will contribute the labor and build it over the next 2 weeks”
  • not : “there’s too much dust coming from the woodshop and we have to do something” (this is just an agenda item) (we decided this sentence is probably unnecessary)
• anyone that has come to at least 2 in person meetings is allowed to vote (you’re allowed to vote during your 3rd meeting)
• voting is counted both during the meeting, and online for anyone with voting power (based on the meeting notes) - the vote count is not finalized until one week later (ie. finalized at the start of the following weekly meeting)

voting proceeds as following:

1. first we count "stand aside votes". stand aside meaning you dont care/arent super in favor of the proposal, but that it doesn’t contradict your core principles
2. then we ask if there is a block vote - Block meaning the proposal stops - means it violates a basic tenant of your principles - should essentially be used in cases which you disagree with something to the degree that it passing would mean you would leave the group - Ideally most votes fail from stand asides and not blocks
3. in order for a proposal to pass it must have at least 3 votes “for”
4. based on the discussion that occurs during the meeting and online afterwards, it may become evident that the proposal is flawed in some way, and could be improved. - Proposals cannot be revised after voting has begun, but a proposal can be withdrawn by the sponsor. - Anybody can create a new, revised and improved proposal

Comments

 

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