Software for making "assembly manuals"

Communities Education
16

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
17

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.

6 Likes
18

Thanks for all your work on GitBuilding!

3 Likes
19

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:

2 Likes
20

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

1 Like
21

Great that you have funding for a new editor. Really excited to see better editors. I would caution exceptionally strongly against wedding it to the old DocuBricks XML standard. It is inflexible, hard to diff, and behaves badly in a Git repository.

The best way we can all be compatible is to have a similar underlying data model. @bhaugen and @jarancio have both talked to me about the importance of defining the data model that underlies GitBuilding.

In GitBuilding we have focussed very much on how to minimise data duplication and increase the flexibility to document more and more complex projects. We had to reorganise things a few times on the way as we found limitations to the approach. We iterated towards our current semantic data structure.

The value of GitBuilding is not the software, the software is bodged together by me, and the editor (as you have noticed) is beyond basic. The work we poured into it over the last 3-4 years has been on how to make the data flexible. Please, let us talk about the underlying structure and how to make that work together. If we get this right then building some a WYSIWYG editor is just software engineering we can outsource.

We need this community to get behind a standardised format. I have been looking for funding to get more people into a room (or a virtual room) to discuss this, so that we can make sure everyone’s needs are catered for, and so we can make the format extensible for manufacturing, quality control, etc.

4 Likes
22

Yes, let’s set up an open video call in March, when my new project team members start to discuss a way forward.

XML is just a basic data format, not for Git, and can be left out without problems. What’s valuable from our years long iterations in the DocuBricks project is not the data format, but the nomenclature (https://www.docubricks.org/software.jsp) and basic modularity concept. Let’s see what makes sense to make compatible and where each person sticks their favourite tools and languages (I know you have very strong views there, Julian :smile: ). Us unites the aim to have a modular extensible and easy to use (from each of our perspectives) documentation tool that should use the cool Git version control capability of GitBuilding and that can be copied into any repository/blog.

1 Like
23

I would be interested in sitting in on this call when you have it.

1 Like
24

Noted, the start of this semester is really intense for me but I hope I can make time soon.

25

After a long time, found it:

image
image767×487 59.3 KB

The app is called “facet”:

I do not know if this app can be embedded in a static page, so I made an issue to check it out: Spelunk "facet" code for embedding Hypothes.is comments (#6) · Issues · Open Lab Automata / Pipetting GitBuilding Docs · GitLab

1 Like
26

I’d suggest the one I told you the other time, https://readthedocs.org/ (example)
Not exactly LIBRE, but you should check Wikifactory example

1 Like
27

Hey, we found a new team member here in Chile to work on an interface for the GitBuilding documentation software. It would be great to have a joined call early March when he starts to discuss ways forwards!

6 Likes
28

Do you have a link for this open standard?

Cheers!

1 Like
29

I couldn’t find the free access links for Dozuki. Does anyone post here, if they find. My guess is that they discontinued it.

1 Like
30

https://www.omanual.org/

1 Like
31

Thanks @kaspar for the open manual link!
Bucknell University uses Dozuki, @scientist, for much of their maker work.
The Bucknell SpeakerBox Assembly is how I reinforce much of the introductory skills content in my maker course, before they are ready for Open Source Hardware projects.
Speaker Assembly 2019 - Bucknell Makers (dozuki.com)
Dozuki did make a $50 per month deal with me to experiment with similar training displays. I used it for several months, but my university wasn’t ready to commit to a full software license.

1 Like
32

Thanks! Is GitBuilding trying to implement this standard or diverge?

33

In Gitbuilding we have implemented a completely separate data format. We do have an open issue to implement oManual import/export, where import seems like the more feasible one since Gitbuilding is much less strict about structure than oManual.

3 Likes
34

Very cool! I’ll take a look at your data format then. :+1:t2:

1 Like
35

Hey everyone, I just found out about the “Ubuntu tutorials” platform.

It apparently generates instructions from contents in Discourse:

Very simple and nice.

image
image1504×569 85.8 KB

2 Likes