Software for making "assembly manuals"

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!

2 Likes

Let me paste this screenshot from prusa’s site, IMO these instructions are much better than LEGO’s

Also, some repurposing ideas:

  • Use wikis and HTML templates for content.
  • Use hypothes.is for online annotation, commenting and discussion of the instructions (example here).
2 Likes

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.

5 Likes

+1 for GitBuilding. I’ve documented one smaller project in it over the last couple of weeks and intend to keep using it.

2 Likes

+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!

4 Likes

Great! Thank you for the links and information <3

We’ll try both of them.

2 Likes

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.

3 Likes

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.

1 Like

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 :stuck_out_tongue:. 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 :slight_smile: thank you.

Thank you as well Tobey, it looks great!

3 Likes

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.

1 Like

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.

1 Like

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!

1 Like

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 :sweat_smile:

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.

2 Likes

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?

1 Like

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 :slight_smile:

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!

1 Like

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.

2 Likes

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.

5 Likes

Thanks for all your work on GitBuilding!

3 Likes

Atom/RSS feeds

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 ABCDEFGH is the group “key” which you can find from the Hypothesis search field when you enter the search term group:groupname

which 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:

Hipothes.is API

This is likely a more flexible way of getting and manipulating annotations:

1 Like