Documentation is key for OSCEdays and ACTIONS. It allows us to connect and learn from each other and make progress together. But how to document? This topic is a collection of possible or suggested ways. Pick what fits your project or ACTION.
(Related topics: Why To Document? | How To Document?)
Keep in mind, that good Open Source documentation is always editable. ‘The source is shared in the preferred format for making modifications to it’ (OSHW definition). So don’t share PDFs for example but editable formats like .pptx .odf .doc .svg etc. where it is possible and makes sense.
#Contribution To Something Already Open
Maybe the ACTION or activity is about contributing to something that is already open or has an Open Workflow (see below) like Wikipedia for example, or a data base or code base on Git HUB. If you contribute to this projects the documentation is often already happening in their structure. But please make them post a link to their contribution on the OSCEdays forum. So others can see how it works and get inspired.
#Audio/Video Recording
You might think about recording your ACTION or activity with video or audio and to upload the recordings afterwards. But keep in mind: Most people don’t want to see hours of video. They just want an essence or the conclusion. If you have the time and energy for it you can edit the video or audio afterwards. But you can be smarter and just ask the participants for a short feedback or an answer to one or two questions and record this in a 3 min track and upload it directly from your phone for example.
To get an idea what to shot and show with a camera check this poster from @cameralibre made for OSCEdays 2015
Download in Hi-Res: PhotoVideoGuidelinesposter.pdf (679.2 KB)
#Detailed Background Information – Explain The Problem
Is your ACTION or activity about tackling a certain problem? Give detailed explanations of the problem and provide background information to allow people to really understand it. Not ’We have a problem with water’ but more specific. Share materials, data, software, upload design files or pictures to the web and share the link to them etc. What have you already tried and what did not work? This is a documentation of the problem. And it will allow people to learn and maybe help.
#Write Ups, HowTos, Tutorials etc.
This is what many people think is Open Source: Detailed step by step instructions (HowTos, or Building Plans) or write ups of discussions. And it is one possible way indeed.
Take the time and explain people in detail how they can replicate your project or process. If your project is a hardware project you can gain some inspiration for things to share from the ‘Best Practices Of Open Source Hardware’. And also Sams topic about ‘How Can I Document My Challenge’.
If you are describing a process that can be repeated at different locations think about writing it down in the form of an OSCEdays ACTION.
You can create this documentation here in the OSCEdays forum – as a new topic or in a comment. Or you create documents you share download links for here in the forum.
If you are creating an ACTION and you ask people in it to document what they do by creating a new topic on the forum, make them name their topic in the following way in order to show the relationship to your ACTION: Put in the name of your ACTION the key part in CAPS, like: ‘ACTION – Creating a MAP OF SHARING Possibilities in A City’. And ask for the documentation to take the part in caps and put it in ‘[]’ in the front of the documentation. ‘[MAP OF SHARING] – San Francisco’
Ask them to link also back to the main ACTION from the introduction of their topic.
#Open Workflow
Come up with an Open Workflow, install a public collaboration process. This is how Open Source software gets developed for example on GitHub. A team is collaborating. But instead of storing shared design files in a hidden folder and communicating via email all the team communication is in the public along with the documents they work on. Everyone can follow the discussions, study the code and follow the development. An Open Workflow means creating documentation while you are working! Documentation isn’t a thing you do as some extra work after the actual work is done. Check out what the OSCEdays Board of Stewardship is doing – it has a complete open workflow.
#A FORM, Or Survey To Fill Out
An ACTION could ask the people running it to fill in a form or complete a survey with simple questions during or after the ACTION. Maybe the form is a tool or structure you use during the ACTION anyway (like in this example). People might just post a photo of the filled out tool or form. But try to find a structure where a photo still speaks. A picture of a wall with sticky-notes is not necessarily a working documentation. Try to design a process that already produces understandable documentation (see also below under: Open Workflow)
If you decide to use a survey you can think about something very elaborated almost science like or just something very simple: For example ask each participant for ONE major learning and/or maybe ONE remaining question. And just write that down.
A possible way to enable documentation is to provide an editable document to download, fill in and upload when completed to a comment in the topic under an ACTION or just ask them to post their answers directly into the comment. Make sure it ends up in a place, where others can see it and benefit from it as well.
Questions? Ideas For More? Post A Comment.