Idea: Members Handbook (Feedback requested)

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.

3 Likes

Excellent initiative. I’ll take a look and I’m happy to help in any way I can

Looks great and is refreshingly easy to navigate.

I think some of the pages are a bit long
E.g. https://bookstack.naxxfish.net/books/tools/page/table-saw---scm-si12

Maybe split them into sections with TOC at the top?

1 Like

The content is just lifted from discourse in hat case but yes further work to improve the layout for this format would be needed.

Most of it is induction notes for which there is a separate section for this kind of thing.

Great!!!

I think it would be great to have everything in one place and editable and I think you guys will do a great job.

If you’re prepared to spend the time doing it, we should be encouraging you to do it.

Gets my +1

1 Like

The link to the prototype doesn’t work for me. If says bad gateway.

Also would I be able to update the tool page for lathe as and when or would we need a “final” page to put in the handbook?

Anyone would be able to edit pages (as is already the case with #tools) - it’d just look nicer and be better organised :slight_smile:

I’m getting ‘bad gateway’ too. It worked for me before

@naxxfish may have switched it off. I’ve pinged him as it’s only a demo.

Ooh blimey.

Yeah my server got rebooted over the weekend for security patches, and that site isn’t set to come up on reboot (since it’s just a prototype for now).

It’s back up again now :slight_smile:

1 Like

So the content in the handbook would update automatically if any changes were made to the relevant pages on discourse?

The pages would no longer be hosted on Discourse at all, they would be moved to the handbook where members would still be able to update them.

1 Like

My instinctive first reaction to this idea was “do we really need another tool, couldn’t we just tidy up Discourse a bit”. But having read the thoughts here and on Telegram, and looked at the demo site, I am increasingly sold on the benefits of having a specialist system for keeping all the documentation clean, organised and easy to search - sepearte from the necessary but busy traffic of our discussions on discourse.
It would be nice to think that by the next time we accept new members we’d have a nice neat introduction document for them to read.
I’d be interested in logging and trying the editor, for comparison to Discourse.
+1 from me so far!
Thanks to @unknowndomain and @naxxfish for putting this together.
A few thoughts:

  • can images be embedded in page content?
  • edit permissions - can this be varied by page based on membership system permissions - so certain content is only editable by relevant techs or directors, such as induction guides or key policies.
  • view permissions - can this be varied by page based on membership system permissions - eg. so certain content is only visible to relevant techs or directors, such as instructions for servicing tools which should only be carried out by techs, or details of where keys for money boxes are kept.

Certainly! It works in the same way as it does on Discourse - the only slightly labour intensive part of migrating content from Discourse is that images will need to be re-uploaded to the bookstack site (as embedded images in Discourse are also hosted by Discourse, and given relative links)

It is possible for Bookstack to use LDAP as an authentication backend only. However, the membership-system does not have a LDAP backend yet, but it’s in the backlog. Once implemented this would mean that users could log in with their membership system details.

The role membership, unfortunately, does not get set automatically via LDAP. It may be possible to build an integration with the membership system that adds users to those roles automatically based on permissions (like we do with discourse), but that’s not really been looked into yet.

Each role has a set of global permissions:

And permissions for roles can be set per book, chapter or page based on role, with different permissions (View, Update, Delete) like this:

1 Like

great, looks really powerful. And if there was a desire to limit permissions in certain areas, it’s not a big job for someone to manually assign roles to techs/directors.

I guess the images wouldn’t be too big a job if shared by many hands reviewing and editing initial content.

COuld the permissions be managed by LDAP through SAML somehow?

Not unless we hacked around with Bookstack. Not entirely out of the question, but probably a fair bit of work!

Greetings from the antipodes - I have been following Discourse for a while, and picking up helpful ideas for the free public access FabLab/Makerspace I work in here at the State Library of Queensland (and thanks for sharing, by the way).

Here at The Edge, we have been developing a documentation solution for our facilities and programming for the last few years, and it is about to go live to the world in a month (late June). Following Library policy, it will be released under CC (non-commercial) license, and I would be chuffed if your group was able to find anything useful in it.

We have some similar equipment to you (a Trotec laser, a commercial CNC, sewing machines etc etc), and not only have documented all our procedures for maintenance and troubleshooting, but also safety documentation, induction paperwork and other (hopefully) useful things. Most of what we do is develop, test and distribute hands-on workshops for use in library makerspaces , and all the procedures, suppliers and design rationale will be on the website too.

We have chosen Dokuwiki as our platform, but this has the capacity to output flat files and PDFs, so migrating stuff to your platform will hopefully not be too difficult.

If any of this sounds interesting or useful, please get in touch (Peter.Musk@slq.qld.gov.au). If you want me to send the URL for the Wiki when it goes live, just provide your contact details.

And keep up the inspiring work.

Peter Musk

3 Likes

Thanks for the input. It’s great to know what’s going on elsewhere.

We recently had a couple of makers visiting from USA and it was fascinating to hear the different policies and solutions

Perhaps we could have a section for Global Makerspace projects?