Myself and @naxxfish have been talking about the issues with documentation at Makerspace for ages, and we finally decided to prototype an alternative.
What is it?
The idea is to reformat content from across Discourse and WordPress and Google Docs into a canonical member’s handbook, a organised living document that contains all the key information a new or existing member would need.
The best way to understand what it is and could be is to checkout the prototype we’ve created using much of our real, original content.
This is very much an ALPHA prototype, we’re looking for constructive feedback on whether this is useful and what does and does not work, and whether we should move this forward.
Checkout the prototype hosted on Chris’s server.
Whats the point
Although Discourse is great as a forum, it’s not a content management tool the content is nearly impossible to find using search, and there is a lack of ability to categorise the content, and enforce that posts are wiki by default, people accidentally post into documentation categories occasionally, and sometimes start conversations on these pages.
By creating a https://handbook.southlondonmakerspace.org site we can point all new and existing members to this place as a resource, couples with a possible new @librarian role and an periodic edit-a-thon to review the freshness of content, we can ensure that things are accurate, and well documented.
Rationale
This was born out of our own frustrations at trying to find things on Discourse, as an example: try looking for information about what to do when the door/shutter won’t open/shut with a search time like “door broken”.
Considerations:
- Members don’t want yet another complicated tool to learn.
- Members don’t want to learn a new mark up language (must support Markdown)
- Should be able to support single sign on with existing Makerspace logins.
- Should be wiki like.
We looked at many options, and evaluated three main options, MediaWiki (Wikipedia’s platform), Bookstack and Wiki.js.
Why Bookstack
We’ve built a more fleshed out prototype on Bookstack as has a unique approach to organising content into Books > Chapters > Pages.
- It supports Markdown.
- It has a relatively simple UI with good mobile, tablet and desktop support.
- It supports LDAP for single sign-on with the membership system, no extra accounts.
- It had PDF export.
- It has simple image upload.
- It has Automatic table of contents.
- Search is very good.
Editor access
If you’d like editor access contact myself or @naxxfish.