Skip to content

Documentation

documenting

If you didn't document it.. it didn't happen.

As in Fabricademy, also in SheMakes all the build up knoweldge is fully documented in order to be replicated by whoever is looking for tools to explore paths with their community, large or small, or all ages and belonging to different stakeholder groups.

GUIDELINES for documentation for new Labs

Transfer Labs feed from and into the shared Open toolkit of Shemakes. We work in this online Open Toolkit in our fabcloud gitlab, using the simple markdown language to enhance and style the content we produce all together.

Structure

The online repository is structured in 4 main sections:

  1. Welcome & Onboarding
  2. Learning path repository
  3. Innovation services repository
  4. Documentation

In the activity sections (2 & 3 of the list above), we have multiple layers of information coming together.

  1. Each activity type has a folder for documentation - the text part ( .md file) is your main target
  2. Each activity type has a folder for the images (example: ../images/WP3/wool/xx-xx) which can be stored there and linked in the page you are editing.
  3. Each activity has templates for documentation adapted to the specific task where necessary
  4. New sections are created, adapted and developed together during meetings

Quick learning materials - Git & Markdown

Markdown is a simple coding language, online you will find many extra resources if necessary, from simple cheatsheets, to extensive docuemntation. We have collected a few of the resources we use below:

  1. Documentation handbook In the "documentation Handbook" you can find the learning resources of how to learn to code in markdown:

    1. Documentation Handbook
    2. Editing in Gitlab
    3. How to add content in Markdown images, text, etc
    4. Optimizing images

  2. Theme - is called Material, you can find info about it in the link below

    1. material for mkdocs - https://squidfunk.github.io/mkdocs-material/

  3. Templates for documentation of the activities See each activity in this open toolkit to find a template and examples of how this is used, adapted in each action that was documented.

Step by step


do i need an account?

To contribute to the shemakes toolkit, you need to create an account on fablabs.io, we use this login into Fabricademy's fabcloud. Do you have a FabLabs.io profile?

  1. Yes, i have one - Great, go on to get access!
  2. No, i don't have one - No worries, make one here
I need access!

Transfer Labs can:

  • check your login with your fablabs.io account here
  • please inform your guru / mother lab as soon as you have a profile, including your username so we can grant you access.
  • Once you have access granted, you can jump to Login or how to contribute.

In case of need, please drop a mail to labs-at-shemakes-dot-eu or ask during a shemakes meeting to add your new profile to the project!

Login

Access the repository project here as soon as you get granted access.

or start editing, start here

Remember to choose the web IDE editing, then login using FabLabs.io account at the botttom right.

Contributing to a shared knowledge pool
  • Start with the steps in the quick-learning materials
  • Create a new page in the git:
  • Go to the handbook and click on the git symbol, top right.
  • Open edit mode clicking on Web IDE. With the web IDE editor you can simply add new files to the chosen folder (mirroring each section of the online Toolkit). Folders and files appear on the left side bar of the interface.
  • Click on a .md file to start editing. Name your file coherently to the others and always ending with the .md extension; something like ../..2.-innovation-services/Community-Activities/Workshop-on-gender-equality-opportunities.md
  • To save, click on commit to main branch
  • If you accidentally don't commit to main branch, follow the merge request window and accept. Then a new window should open and let you click on merge request
  • If you are not sure at any point of this step, thats totally ok :) just ask your task leader/activity Guru! (Nuria-Curiosity, Andreea/Elvys-Community engagement, etc etc)
Using a template

When using web IDE, you can open multiple files at the same time, this allows you to copy paste the template into your new activity page. Start editing the template with the details, info, pics and files needed for your executed activity

  1. you can follow the template, edit adding information and images relating to your activity. Sometime you might see comments: text you see in code, that does not appear on the website, this is your task lead leaving you some suggestions based on previous experience
  2. how to add images, links, etc you can find in the documentation links "Guidelines for documentation"
  3. adapt the template, be inventive :)
Feedback & Reflections

It important you share feedback and reflections on the activities you organised, so we can adapt the shemakes journey together!

Fill in your reflections and feedback - defining what worked and what you adapted, how the activity was received/perceived etc make template if we go this way

Ready?

Flag to your WP lead that you are ready/need feedback so they can take action and review/feedback

  1. Nat/Marion WP2 - Ceci/Bea/Ista WP3
  2. WP2 - a reviewing format of 3 reviewers per task
  3. WP3 - Task leaders will review the work added in phase 2


Q&A for Transfer Labs

  1. I want to change the template! - Cool! make a proposal to your WP lead / task Lead, they will be interested in knowing
  2. I want to add a totally new activity: make a proposal to your WP lead / task Lead
  3. I have questions about markdown >> check the Handbook linked here above
  4. I have questions about a specific template >> ask your WP Lead or Task Lead
  5. Log here your Questions as a Transfer Lab
Last update: February 2, 2022