Open Hardware Documentation

image

OPEN HARDWARE DOCUMENTATION & COLLABORATION@November 20, 2019

I am always looking for the optimal platform to develop open hardware projects, there are some good platforms out there, but which one is the best one for us to develop a complex project that combines hardware, electronics, coding, AI and possibly large datasets? And what about project management, our website and even social media outreach?

image

I looked at some official list of Open Hardware projects:

And I read some articles

So below I am loosely exploring different platform and making some short comments about each platforms

Wikifactory

The interface is clear and simple which I like, but it's not really scalable for the future (especially compared to GitHub for instance). They recently added the capacity to view 30 formats of 3D files, which is great. I also like that they are based in Shenzhen. This is a project of their own - really cool project of them https://wikifactory.com/+wikifactory/north-star-build I joined as an individual: https://wikifactory.com/@cesarjungharada created the MakerBay page to host the Coral Reef Mapping Roboto: https://wikifactory.com/+makerbay/coral-reef-mapping-robot - but I think we should use Wikifactory, only for RELEASED VERSION AFTER posting on GitHub

image

Upverter

It's like GitHub for ELECTRONICS (NOT CAD)... https://hackaday.com/2011/09/14/upverter-its-like-github-for-hardware/ Not so great for other open hardware project that have more than just electronics. But really awesome for electronics. Special mention for Fritzing here as well.

image

Hackster

Hackster has a really good community and good interface, but does not really support versioning, history, branches, project management as far as understand. Same as Wikifactory, I think it would be a great place to publish every time we have a version done on github.

image

Hackaday

I read Hackaday and enjoy the blog content, but I do see a lot of troll attitude and “I’m a real hacker and you’re not” in the comment. They do have project documentation: https://hackaday.io/project/168301-arduino-controlled-photogrammetry-3d-scanner, it’s clean and meant for single version. Same as Wikifactory and Hackster, I think it would be a great place to publish every time we have a version done on github.

image

Ning

DIYdrones is powered by Ning - a private social network. It's really good for community communication, not optimal for versioning and mass collaboration.

For their project Pixhawk, they use Github https://github.com/PX4/Firmware I will argue that Chris Anderson (Founder of WIRED Magazine) perceived that the most important part of building a hardware project is the human communication part, therefore picked a private social network to emulate a sense of belonging and more conversations.

image

No wiki, no collaboration platform

Sometimes, best collaboration platform is no collaboration platform. For Open Desk, minimal project management and documentation is the way to go. The website could either be wordpress, it feels a lot like a squarespace - could be magento or another online sales…

Open Desk uses slack channels. Interesting.

image

Instructables

I am a long time member of and I adore the community BUT not great for collaboration and versioning I have to say. I think it is still the best community for young people. The platform and the app are pretty good, but if we want to appeal to professionals, we are going to need a platform that is more robust. Same as Wikifactory, Hackster and Instructables, I think it would be a great place to publish every time we have a version done on github.

image

Wiki

Wikis are great, free and super powerful for mass collaboration and documentation, but they are islands and take a lot of work to maintain. Lots of energy can go into "discussion page" - discussions are great don't get me wrong - but I prefer the brevity and possibility to have multiple branches you have on github

Open Source Ecology front page is a good wordpress and the R&D is documented in the Wiki

Raspberry Pi uses wiki https://elinux.org/RPi_Hub

image

Github

image

Untitled

Originally for coders it's become the most robust platform for mass collaboration

The best documentation I saw there

You don't need to know coding

We built The Marine Litter Detective on Github, and we found it was the most powerful documentation platform out there. http://www.marinelitterdetective.net/ | https://makerbay.github.io/Marine_Litter_Detective/ | https://github.com/MakerBay/Marine_Litter_Detective

It also supports Project Management, you can display .stl files, .csv file, .pdf, .goeJSON, you can even have a full wiki, there are TONS of code for arduino and machine learning, image classifiers there to sort our coral images…

Another powerful feature is that you can sync your local files and remote files, so you are always working on the latest version.

Oh, and by the way, it’s free for open source projects!

GitLab

image

Untitled

Thanks to some friends feedback:

Marcin: Gitlab - https://gitlab.com/ - is the open source version of Github, so you may want to consider the open source version as opposed to the proprietary.

Clément: https://techcrunch.com/2019/07/29/github-ban-sanctioned-countries/Github closed entire projects we were working on for the sole reasons they involved Syrian and Iranian developers. You shouldn't trust them with your data. Self-hosting is the best way.

This table clearly shows that GitLab is a better option, not only for development, but also deployment. https://about.gitlab.com/devops-tools/github-vs-gitlab.html

I can’t seem to find .stl (3D) file viewer in GitLab though

Hum…

My conclusion

I want to migrate most of my projects on github because

  • I believe the platform will be around for a good long time
  • It enables mass collaboration, forking, versioning
  • supports all the file formats we need
  • has project management
  • for my collaborators, it’s really tidy, very appreciated in the industry as part of a portfolio

Once the project is documented on Github, I want to use

  • my personal website to track the progress
  • instructables - because I think the community is super positive there
  • possibly Hackster, hackaday, upverter, wikifactory and the usual suspects: Facebook, Twitter, Instagram to get more people to comment, fork, contribute etc.

I do recognise that GitLab is better than GitHub is almost every aspects, except the networking effect. Let’s start on the standard platform, and we can migrate when the community is more mature.

💡
[UPDATE] I must add Notion has been working wonders for me and my team. It's just so much easier to edit for non-techie BUT easy to break too!

Leave me a comment of what’s your favorite documentation platform for your Open Hardware Project :)