@Tobey I agree that these things don’t mean the same to all people, but I think that is why we ask lots of people and get a “feel for the room”, both on what questions, how important it is to them, and how they think solutions perform.
“Intuitive to get set up” could replace “Intuitive to install” you don’t have to install to start using Dozuki, but getting a login confused me a lot. Essentially what is the barrier to entry.
Other platforms that exist
highly used platforms such as thingiverse, instructables, hackster
Personally I don’t find these a useful comparison. Their target audience seems to be people who are sharing small hobby projects like “I made a disco ball plant pot from an old mirror and took some photos”. These don’t need revision control, and can probably be adapted into a blurb and some steps.
What about the post doc who is spending 2 years designing and improving an ultra high vaccum x-ray analyser, or a confocal microscope? What about people designing an open source car (not science hardware, but I think we want a tool that is generally hardware applicable if we want uptake). What about all the teams prototyping ventilators during this pandemic? They are not going to get this into an instructables page.
For this type of complicated equipment that takes years to develop, you will need to write and edit and changes and reformat the documentation lots of times. If you wait to the end you will just never write it (never writing it is the norm for PhD/Post-Docs). Integrating this with version control is important for back-up and design history (design history is essential to medical certification!), and is often useful if multiple team members are to work on something together.
As the interest grows in open source medical hardware, people will submit their documentation to regulators who will have strict guidelines. If the documentation output cannot be customised to meet the guidelines then they will have to export and reformat.
If we think about simple projects that only need the feature set of instructables, then why not use instructables? I know it is not open source, but nor is GitHub yet is it widely used in this community. I am more interested in in what professional engineers use. So far, my experience is they prototype first (taking some notes) and then the documentation is created in a word-processing tool with 100s of person-hours. The dream for me is to automate much of the tedious parts so at least a useful skeleton of the documentation can be written while you hare in the workshop/lab pototyping. I want a tool that:
- McLaren would want to use when prototyping their F1 cars
- NASA want to use for their next satellite
- We want to use for the OpenFlexure microscope
- Our BSc students find easy to use for their first ever hardware project
Structure
The point about a structure to work from can be helpful is a good point. I think a nice way to do this without loosing freedom is for tools to have templates. I can envision adding a new page and having an interface like this:
This gives you structure if you want it but does not constrain you if you need to get down other information.
Modularity
Both of us agree that a modular or hierarchical data-structure is essential to making elements of the documentation reusable for other projects. I have use the IEEE page to lay out a little bit about both of the data structures and then to go into details about how the hierarchy is defined in BuildUp.
. It takes a command line to start it up. The syntax seems to confuse a lot of people even though it is very similar to the syntax we use here in discourse.
