Lets Discuss Documentation

Lets Discuss Documentation

Saturday’s members meeting gave us the idea (thanks Mark) to host a document the space day (virtually) on Saturday 22nd August). This is your chance to help document various aspects of the space and to do this we need to start somewhere

So we all know the wiki is dead… its been dead for a long time, we discussed using moodle to document everything but having used it recently to I didn’t think it had the capabilities for what we wanted for storing useful information documents so instead we have https://docs.hacman.org.uk this is the hub for getting all the documentation together and its easy to do simply write what you want to document in markdown format (for anyone not familiar with markdown use stackedit.io as a wysiwyg editor that exports as markdown) and add the file to the documentation github repo at https://github.com/HACManchester/documentation/tree/master/docs or email (for now to board@ but this will change) and we will add it to the repo for you if your not a fan of github

I’ve added some generic documentation to it but there are areas of the space I can’t document as I have no clue about them! Note this shouldn’t take away from using the tools & equipment section of the members system for details on the tools but can be used for more detailed information, similarly it shouldn’t be used for training documentation that should be on moodle (but we will discuss moodle and training and inductions another night)

All old wiki content has been moved over to this too so that can be easily edited if its easier

(note the system is still in the setup stages I’ve not yet implemented the ci/cd deployment so that it will automatically update but i will deploy regularly until this is setup)

Feel free to bikeshed the system to your hearts content or be productive, help us document the space and lets get some of the knowledge that lives in our heads into some documents.

1 Like

Sounds great, I’ll move over some of the laser documentation (unless someone else wants to do that) and remove some old event-based pages from the old wiki pages.

There’s quite a lot of things there which are not space documentation - member’s projects and generic advice on using AVRs, etc - do we want them in the documentation site?

So ideally we would keep space documentation on the docs site and things like members’ projects we should be moving into here.

The below kinda sets out where something should be based/used for (its not an exhaustive list)

I would never give up on a wiki. I also like moodle, I did document the operations of an African ISP on moodle and run some courses using it for a national charity, which was very useful as we were able to see who had read what. What that means is someone can be seen to they have viewed content on a particular topic. Though I don’t like the testing aspects of Moodle it may be useful to ask some simple questions about a device.

The way I see it is that the wiki that any member can edit just by clicking an edit button is more like what Tim Bernards Lee produced on his NeXT computer. This is less hierarchical than Moodle, which has a more controlled design. We need both control and flexibility.

Sure we could do with a fixed system, but we are over controlling at the space when it comes to computers. Every time I sit down on a machine at the space someone has set it up in such a way that I can not use the tools I am used to. So I am meant to bring my own computer every time.

The four elements shown by rossy are a good start.

Document the Space Day - At the last Member’s meeting we decided to hold a day where people could come together to document the space / tidy up documentation etc… Today is that day Join this google meet link from 3pm to take part. https://meet.google.com/bru-meze-mqx

The current text on Tools & Equipment says it’s for additional information which isn’t in the members system. It took me a while to find the laser cutter documentation, and even then it’s in a narrow popup window which is difficult to read. I think it’d be much easier to read in the new docs system, maybe with a link to it in the member’s system.

We discussed this on a video call today - the members system will contain basic information about equipment and will link to more detailed information on docs.hacman.org.uk.