osiscoming

Good documentation is key for open source collaboration. The tools available for documentation and collaboration around open source software today are amazing, which is one of the reasons, for the enormous success of this movement. Today we’d like to explain to you the basic operations of the most important tool called „Git„. Git is also in the heart of „GitHub“ – the today’s biggest open-source-software development platform.

In steps:

STEP 1: A Repository

If you want to start a project, you start a „Repository“ where you will host all your files and folders with the code and documentation.

STEP 2: License

You pick an open source license for your work to allow others to work with your code. Without such a license no one can use your code or commit to it in an easy way.

STEP 3: Writing the documentation

If you are not a code-literate, code can look to you like a strange „Alien language“. But coders and machines can understand this language. If you write open source software you will also add comments next to the code, which are written explanations in normal language about what part of the code is doing what and how it is relating to all the rest. This is essential to make it easy or even possible for other programmers to understand the code and work with it.

STEP 4: Forking

If someone finds your project and wants to work with it or „commit“ to it, first thing they do in Git is to pull a complete copy of it into their repository. This is called „Forking“. They have their own version now – their own branch – where they can start to add or change code. Your own repository or branch stays the same.

STEP 5: Pull request

If they think, their created changes or commits, should also be included in your project they can send a „Pull Request“ to you. Then you can check their commits and discuss it with them and others, if you think, it is worth your time.

STEP 6: Merge

If you like the new code you can add it into your repository. „Merge“ the two branches. Now both repositories are the identical again.

This is the very basic and simplified procedure. Some implications:

😀 Different Versions allowed 

If you do not like the changes the other person has made you don’t have to include them back. Maybe they wanted to go in an entire other direction. One chair will have wheels, the other wings the third no legs. But they can all be forks of the first chair. Have a look of this graphic that shows you all the different projects that started as forks from the Debian software project.

And Open Source Hardware?

Is there something similar for hardware? The answer for this is sadly: No. There are many many reasons why it is way more complicated with hardware than with software. To give you just one: You can download a complex piece of software, install it on your machine and use it or change it within minutes. But you can’t download a whole tractor. You can download the building plan. But then you have to get all the parts and assemble them before you can use the tractor or change it. Another is: Written software is already digital and you can just click the „upload“ or „copy“ button. But physical hardware developed in a workshop or laboratory has to be documented – digitalized – first, before you can do the same with it. This is an entire new and different step for your work, that is almost unrelated to the first ones.  

But there are more and more projects in the world trying to make progress with the documentation and collaboration part also for hardware. Some mentions: Wevolver, Instructables, Make-O-Matic, Project Elmyra, IPO-tables, Wiki-Fab.

And here is an image video from a project that seems to have stopped but it shares some ideas and approaches to documentation:

But meanwhile people are using wikis, youtube, their blogs, forums and sometimes even also GitHub.

__

Author of this window: Lars Zimmermann
Join us! Create a window.