LEGEND
image Steps you absolutely have to take!
image Optional steps to make it extra special
In order to make sure your project has open source freedom for others to use and adapt, you need to give it an open source license. Choose from one of these Open Source Licenses:
Copyleft Licenses CC-BY-SA 4.0 CERN OHL GPLv3
Permissive Licenses Apache 2.0 CC-BY 4.0 MIT License
Anything that restricts the use and remix of the project (like NC/ND) or has no license, is NOT Open Source.
Create a description file and put the license text inside your repository. Do this before you publish anything about your project!
Choose a platform that fits your needs. Where will you publish or share content? Eg: github, gitlab, nextcloud, website/wiki, wikifab, wikifactory
Things to keep in mind: File management, storage, accessibility, exchange, version control, contributions, onboarding, community interaction
Describe & outline your project idea. You want to share your project with the world? Give it a name, give it a reason to be & give it a go!
Issue management A place where people can discuss questions and issues with the project. Onboarding / forum connected to platform choice eg: github has issues management and tracking included. If people have trouble making the thing, how to suggest improvements, track changes, bugs.
Generate READ ONLY output files on each platform to visualize the project. Give people access to VIEW and use the project without making modifications or changes. Ability to READ across platforms to view, without having to use proprietary software.
OPTIONAL: Provide a development branch for people trying new features.
Each Release provides better reference and enables people to fork (multiple sub streams and variations of the project) and improve your outcome, spread the word and gain new resources and users.
Share your source files as soon as possible! Original content files, text, sources are essential from the beginning to help understand what you’re doing and with the process of documentation itself.
Anything READ ONLY is NOT a source file! Don’t make people reverse engineer your work to create or adapt something new.
Keep in mind that Git based systems don’t work well with big sized binary files (videos, large photos or PDFs, etc.), you might upload them somewhere else and share the download link.
Someone is taking care of follow-up: responding to suggestions, making changes, fixing bugs. Even if you are the product owner, take care of documentation when you make improvements.
Collaboration is key in Open Source projects and need maintenance, moderation and constant activity.
Create guidance around your project as visually as you can. Facilitate and encourage collaboration with instructions to various target groups.
For example:
contribution guide: how can people contribute
How to guide: how to use the product
user tutorials: how to use the product
developer guide: technical steps for developers
Release the project in early packages. Give it a version number and provide the best access you can. Version control (eg. Git) based platforms can help with this.
Types of release: Unstable release (development), Beta version (pre-release), Stable release (ready package), New upgrades/features etc.
To build up free knowledge for everyone.
Open source helps with access to information in fragile or post-conflict scenarios & areas where you need to build up infrastructure fast and increase capacity. Strengthen your local community and join forces with an international open source alliance!
Be clear on WHY do you do it and able to explain that.
Increase the momentum of innovation with collaborative development & gain access to resources, tools and knowledge by sharing your work.
Connect to the community that is going to use and help develop it.
Find communities that are already using these tools and platforms
Accessibility – you will need to provide a clear structure and give details on how to contribute to the project.
Talk to people, share examples and knowledge.
By collaborating publicly everyone contributes their own resources to the project. Especially in cases where you don’t have all the knowledge or skills to finish a project, it’s the best way to get it done. If you want to save resources by not reinventing the wheel, the best way is to join forces and collaborate. Avoid complicated contracts with an open source license, and share your work with everybody who wants to participate.
Understand the structure of information and processes to explain what you have made. Understand how open source documentation works so you know what to keep in mind: eg, file types, templates, formats, video/photo text/diagrams, step-by-step instructions.
• processes, tools, readme files • How to contribute to this project • Platform choice to collaborate • Back-up structure to do documentation
Know what to keep in mind:
Eg. File types, templates, formats, video/photo text/ diagrams, step-by-step instructions.
Open source guide/building-community/
> Good documentation only becomes more important as your community grows. Casual contributors, who may not otherwise be familiar with your project, read your documentation to quickly get the context they need.<<
> Your README is more than just a set of instructions. It’s also a place to talk about your goals, product vision, and roadmap. If people are overly focused on debating the merit of a particular feature, it may help to revisit your README and talk about the higher vision of your project. Focusing on your README also depersonalizes the conversation, so you can have a constructive discussion.<< Opensource.guide
Any questions that comes up in the process might be relevant for collabrators so include answers to these in you documentation!
CodiMD: Open source platform to write & collaborate on markdown text to host on your own server and that you can use for free. https://github.com/codimd/server https://demo.codimd.org/
HackMD: Closed source markdown platform similar to CodiMD.
Markdown: Lightweight markup language with plain-text-formatting syntax. Easily written and displayed by lots of platforms. Because of its simplicity it’s useful for documenting your user guides, meeting minutes and readme files. Not meant for layout/design!
Issue report: When something isn’t working, alert the developer to fix it! When you find something that can be improved, suggestions to make or general technical issue.
Feature request: Special type of issue report that shares ideas to improve the project.
Fork: When you copy all the files of a project into a new repository, name it and create your own new offshoot – make the changes yourself.
Merge/pull request: Where you merge your new work back into the existing repository, with the additional features or work you have done.
Issue tracker: Management area for your issues.
Telegram: It’s a text based messenger that you can use to share files, management teams, have news channels, to help organize your project.
GitHub: It’s a text based collaboration platform, that allows you to shae the source (code/text/files) of your work and invite other people to adapt, develop, work on it and contribute to new versions!
>> (/grt/): is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files. << /Wikipedia
GitLab: An open source example of git based development platform – mainly software, can be used for hardware and open source project. You can work on decentralized, personalized project on these platforms. More tools you can use for free.
The magic about git is you can work on your computer locally, and push it later to the repository. The platform is the project & file management front end, where you track issues, and feature requests, manage you community and collaborate with the team.
Repository: A place where your files sit/are stored/but also shared… Public Open Visible. Keep a local copy of your files on your computer, especially when using any online/cloud platform or demo version.
Wiki: A website or database developed collaboratively by a community of user, allowing any user to add and edit content. Wiki is also a Hawaiian word which means “fast or quick”.
Creative Commons Licenses A set of rules you can choose from to release your creative work. Some of the CC options are open source licenses, like CC-BY or CC-BY-SA where BY=attribution, and SA=share alike. Creativecommons.org
“That’s what the magic is about open source! You can take multiple ideas, realized – although your idea takes a new path from the original. Whenever you fork something and you IMPROVE it by adding features or new design. Always link back to the original design. In case you fork something, make it known. Look at the license that it has and follow the terms and conditions of license before you start!” Timm Wille
There are different types of Open Source Licenses to choose from.
>> Copyleft or Viral licenses allow anyone to use, explore, distribute or modify the projects, but you must publicly contribute and commit all the modifications that you have made to the original project. The original project is kept updated, and it has evolved. A person or organization using or depending upon it is legally bound to share their own modification, help maintain the project, and contribute to the updates.<<
CC-BY-SA 4.0 Creativecommons.org/licenses/by-sa/4.0/
CERN Open Hardware Lic. www.ohwr.org/project/cernohl/wikis/home
GPLv3 Tldrlegal.com/license/mozilla-public-license-v3-(gpl-3)
Mozilla Public License 2.0 Tldrlegal.com/license/mozilla-public-license-2.0-(mpl-2)
>> permissive licenses allow creators to release a project as open source so anyone can explore, use, modify and distribute it in any way. Also known as “copyright licenses”.<<
**Apache 2.0 ** www.apache.org/licenses/License-2.0
CC-BY 4.0 Creativecommons.org/licenses/by/4.0/
**MIT License ** En.wikipedia.org/wiki/MIT_License
If you choose CC-NC Non-commercial or ND – no derivatives – these restrict use and remix of the project. Therefore it is NOT Open Source. Also, if you don’t choose any license then you have not given permission for anyone else to adapt or use your work.
Understand what platform to use (versioning*):e.g. GitLab, Wikifactory. Version control allows you to keep track of each new contribution and releases! * Each change is embedded in history of repository.
DESIGN
SVG – open illustration format
JPG & PNG (these are OUTPUT formats) – understand the best practices to save, name and share your actual source files!
TECHNICAL FILES
CAD Files – technical drawings
STEP/STP & SVG – interoperable formats in case your working file is not open software based STL.
PNG & PDF – provide platform independent viewable formats to enable more people to read, understand and share the project/concept. (For each release!)
WORDS
Text files – Odt / docx / txt / pad / Readme
**BINARY FILES **
Videos, photos and other big sized files (e.g. non-text-based, packaged) should either be outsourced to an upload platform (Cloud, Video platform etc.) or kept to a minimum.
TO DO’S AND TO DONT’S
gdoc to gdoc or not to gdoc? Why use/don’t use? (issues for privacy, google using your data as product, force you to sign up with email address to participate) ............. .... ... .... ... .. Privacy Data issues – open source doesn’t mean you share everything, need to protect the privacy of other people ............. .... ... .... ... .. Contribution List to see who put what effort into x project – git based documentation let’s you see who did what in terms of project – if you make a product or service for instance.
• How do you open your work to collaboration? • Does it make sense to use a git, cloud server or wiki? • Where do you want to “host” your community? • What are the steps to make contributions open?
What are you sharing? Is it documentation of a product, technical process, hardware, software (sourcecode), concept/idea, book, training module? Understand the framework you need based on the open tools available.
The main thing is you always share the “source code” that means all your working files that you use to create this output: that means technical drawings & CAD models, text and svg files for design layout.
What type of content are you documenting? This will define what tools, platforms or processes to use!
Examples for platforms according to use-case • Open hardware & software ‘source code’ repository for files )original, versionised, compare): Github/Gitlab • Step-by-step Instructions: wikifab/wikihow • Text based collaboration: etherpad, codimd
Create a visual process Show technical diagrams, illustrations, roadmaps
>> An open source project with no license attached – no matter how remarkable it is – is avoided for use by everyone. For others to use, distribute, and build upon projects the creator must have first given their express permission outlining use of their designs, constituting it as open source. No license, in practice, means you are abandoning your work in the wild instead of owning it and sharing with others. <<Usama Abid on Medium
Open by license: Medium.com/inventhub/open-source-hardware-the-licenses-a244733e6cb7
1. Select you project to document: in this case, electronics or hardware repairs. 1. Create a guide, simple how-to repair radio, mobile phone or how to use a soldering iron etc. 1. Technical examples, diagrams, outline steps and give overview for the basic process.
This event involves hands on use of tools to repair broken appliances. The #ASKotec materials will come in handy, as people who have their appliances or electronics broken see the repair process and learn the skills to repair their gadgets next time. Document the event on Wikifab.
WHAT IS A REPAIR CAFÉ? Repair Café is a space to repair broken electronic appliances of the public. Ranging from phones, radios, television and solar panels and more. The Repair Café as an open source documentation scenario combines training, workshop and event aspects. Trainers help community members evolve within their sessions.
TOOLS • #ASKotec kit • Soldering iron • Hands • Camera • Computer/laptop
MATERIALS
• Soldering wire • Wires • Soletape • Masking tape • Internet • Pens and • Notebooks (Documentation)
SERVING SUGGESTION Audience: Build your community, people with repair needs, keen to learn or create spaces for community interaction, socially & ecologically minded!
Resources: Repaircafe.org
Get more insights via Wikifab.org/wiki/repair_Cafe’
METHOD Instructions to make it tasty! •Team Setup
............. .... ... .... ... ..
Provide Blueprint of space, briefing teams
• Space Setup (repair/maker space)
............. .... ... .... ... ..
Reception team near the door / entry Expert tables (U/C Shape) Waiting Space / Community Management
• Registration Process
............. .... ... .... ... ..
Register devices under the owners name Tag devices with sticky notes and numbers Sort devices that can/can’t be repaired
• Repair Process
............. .... ... .... ... ..
Tool Keeping &maintenance
• Education
............. .... ... .... ... ..
Share the skills and steps required to do this at home!
• Documentation
............. .... ... .... ... ..
Documentation & list of all repairs to track success Statistics – repairs completed, diagrams, pictures.
• Social Media
............. .... ... .... ... ..
Share Repair Café success stories on your social media channels. Use hashtags #ASKnet #RepairCafe.
#ASKnet Open Training on GitHub
Expamples of other training content:
OPEN TRAINING GUIDE
How to set up your own training formats
Github.com/opencultureagency/Open-Training-Guide
Insert QR code