Dear all,
We’re starting a new project and wondered how we could generate assembly documentation.
Doy you know any libre platforms, web templates, apps, etc. to generate instructions / assembly guides?
There are some example websites around, such as: Prusa Knowledgebase, Instructables, or Hackaday.io.
Thank you!
Let me paste this screenshot from prusa’s site, IMO these instructions are much better than LEGO’s
Also, some repurposing ideas:
What you are looking at for the Prusa manuals was written in a system called Dozuki. It’s a proprietary tool/platform but they do use an open standard for the format and give free access to projects that make their instructions public.
For the OpenFlexure project we have been developing our own free and open source tool:
Some of the features you highlighted in the Dozuki screenshots don’t have comparable versions in Gitbuilding yet but we are working on it and open to contributions.
+1 for GitBuilding. I’ve documented one smaller project in it over the last couple of weeks and intend to keep using it.
+1 for gitbuilding also.
If you’re interested in documentation with a heavy dose of quality assurance or other survey-type questions, you can also check out surveystack.io. It’s free (libre and beer) and web-based.
We use it for assembly and qa/qc for our Reflectometer we make.
Here’s an examples from our process:
https://app.surveystack.io/surveys/602bd8bf04aa9e00010188d2
You can also run usb or bluetooth uart (serial) commands from the device, or talk to items in your network via http or other requests in the app. In this case, I have embedded scripts which initiate the device to run an operation, and then get info back and display it to the user.
https://app.surveystack.io/surveys/60b2da788bb0760001be45a9
More on the docs page →
Happy to give a walk through if it’s useful - just holler!
Great! Thank you for the links and information <3
We’ll try both of them.
www.docubricks.com is an early documentation tool I designed with people in the GOSH community. It comes with an offline editor to enter the documentation (easier than version controlled online platforms) that creates an open source standard XML file of the documentation, but currently the documentation can only be rendered and viewed on the DocuBricks website, as we have not been able to implement further software development steps recently. Nevertheless, it has been used successfully for a number of Open Hardware publications and might be of interest for you. Last year we started a compatibility initiative with the newer GitBuilding to be able to use modular documentations interchangeably on GitHub in Markup language and export as XML and edit with an editor, but we have not implemented this yet.
Interesting topic, sorry I don’t have a tool to suggest, but I have question:
I was recently looking at the comprehensive assembly instructions for the OpenAstroTracker project, which is part of their project wiki. Any idea what documentation generation system they are using, if any?
Sorry silly me!! I just found out it’s using Wiki.js. Looks very professional but probably not best suited for hardware assembly documentation?
@kaspar Thanks for the reminder about GitBuilding +1. I’ll remember this the next time I or someone I know works on documentation.
Updates!
We’ve started playing around with that one and got it to “work” on gitlab pages, with hypothes.is annotation.
Though that was the easiest part 
. This change only requires adding a template file to the gitbuilding project (see this commit) also the hypothes.is embed instructions and the gitbuilding html template customization documentation page.
It looks very promising! Thank you.
Hi hpy! Indeed Wiki.js seems to have improved a lot over the years. The last time i went with Dokuwiki. Perhaps I’ll give it another try soon 
thank you.
Thank you as well Tobey, it looks great!
Very nice project!
I am really interested in this initiative, actually this tool is something I want to create for medical hardware assembly. What I have in mind is something similar, with capabilities to launch scripts/software during the assembly process so that it can make auto-calibrations, generate tailored-made config files, and so on.
Not sure what stage you are at but if you are looking for help I’d be happy to be involved one way or another.
Looks really promising indeed, I can see how the annotations could be useful and I would never have thought there was something like hypothes.is that could do this and could be combined with Gitbuilding in this way. Nice work.
Not sure which tool you are talking about exactly but for Gitbuilding contributions are always welcome.
Sorry, I read to quickly and I understood your project aimed to generate assembly instructions. This part is just a requirement, not the purpose.
I am still interested though, I have a similar issue with my project. It is good to have some suggestions here, there are some nice projects around to acheive this!
Hi all,
Wow, I was away for a week and thread has exploded full of chatter about documentation and GitBuilding. This is fantastic, I should take more time off 
I will look into this Hypothesis annotation later today. It is also great to have a non-English speaking user, as I am sure there are a load of things we need to improve to make the documentation more international rather than so English focused.
I also have a long list of things that @jmwright has spotted recently. It is very exciting to have real users, it has been developed primarily for OpenFlexure, but kept general enough that we hope others will find it useful. Hopefully, we can make some real progress in the next few months.
I just had a look at the hypothesis notes. This is fantastic. I think having notes directly on the project documentation is fantastic for many projects. For others it would be great to have hypothesis enabled for drafts. For this we would need way to permanently store some drafts.
Do you know if there is a way to get a list of all comments/notes inside a specific site?
Hi!
I don’t have experience using APIs, but it seems that it can be done rather easily with a search request, limiting results to a specific URI. See h’s API documentation here: Hypothesis API documentation (v1)
Also…
There are some integration examples here: Tools, Plug-ins and Integrations : Hypothesis
General information for developers is here: Annotation for Developers : Hypothesis
There seem to be various communication channels there; perhaps there is a place to ask about our use-cases.
It is (of course?) open source software, so it may be self-hosted if convenient
Hmm I’m not sure I followed that part. I’m still not familiar with the gitbuilding workflow.
How would you use that list?
Best!
My thought was if I was updating docs for a big project based on comments I would like to be able to see all the comments and check I have actioned them. If not I have to go to each and every page checking for comments and I might miss something.
I have just released v0.9 of GitBuilding. A summary of the changes can be found on GitLab
Thanks to @jmwright who has given a lot of feedback and found some bugs.
Thanks for all your work on GitBuilding!
I got an anwser to that, it involves parsing some XML output from these links:
Reply from Chris Aldrich at the Hypothes.is Forum:
Here’s a few examples for following feeds of annotations for some variations that hopefully will get you sorted:
Particular site: https://hypothes.is/stream.atom?url=www.nytimes.com
Tag: https://hypothes.is/stream.atom?tag=OER
user: https://hypothes.is/stream.atom?user=username
group: https://hypothes.is/stream.atom?group=ABCDEFGH
where
ABCDEFGHis the group “key” which you can find from the Hypothesis search field when you enter the search termgroup:groupnamewhich will return a URL:
https://hypothes.is/groups/ABCDEFGH/groupname?q=that indicates the necessary key.
Here is some interesting stuff on the atom stream thing:
This is likely a more flexible way of getting and manipulating annotations:
Hey folks, great progress work!
It’s fantastic to see all these useful features develop.
A while ago we started a conversation about a little effort to redesign compatibility between GitBuilding and DocuBricks to allow the conversion of formats. Is still still of interest to the community?
My observation was (in particular in a bio-focused research community) that GitBuilding is hard to use for many researchers, and a simple editor to create and modify could help. DocuBricks has this but the editor is not close enough to the final product (it’s not yet - what you see is what you get (WYSIWYG)- kind of style) and the conversion from the standard XML format required special software. The development goal for DocuBricks was always to rewrite the Java code as JS in an Electron environment in a WYSIWYG style, allowing easy modification on GitHub, anywhere online and also on the desktop. In my new project I have a bit of resources to pick this back up and create an editor compatible with GitBuilding to host and track projects, and with with DocuBricksw XML standard. But before we go ahead I’d like to hear your thoughts on the need, opportunities and challenges to make sure we can do this together and in a sensible way.
Best wishes,
Tobias
