My notes from the introduction part of our session - Feel free to edit this or tell me - I didn't get everyone's names...
Marc - has tried in the past to set up documentation platform for biology (wiki) but was hard to get others to contribute
Kina - Uses instructables, but it's hard to update
Ali - Makes a lot of his own tools, needs to document them
Bengt - Really bad at documenting my own projects
- Working with teenagers
Daniel - Works at the university, documentation is crucial to hwat he does
- Keen to write documentation that allows others to see and understand what he does
Sha?? - Educator & researcher, slowly starting to document what he does
- Documentation is really important to share what he's doing
Bethan - How can I apply the principles of documenting hardware to wetware?
- Has worked on open appropriate tech, an article in appropedia - but how to do better
Gustavo - researcher, hoping to get better at documenting
- Also working with teenagers
- How do you manage time - would be good to have a methodology
Fernando - Has tried to document projects in the past (wiki, git) - looking for a better platform
Marina (CTA) - many students at the beginning of studies, how do we inspire enthusiasm about documentation. Also, how do we manage versions? Also, documentation can mean usage manuals, teaching materials, assembly instructions. Could we standardise how we organise documentation?
Veyron = organisation doesn't document very much, but it would be good to do that to learn more efficiently
Tobey - it's crucial to get the documentation right if we're going to build on each others' designs. Worked to build DocuBricks, and JOH
Gina (project manager WCS) -
Doran - want to make it easier for farmers to document their practices - and to document on-the-fly rather than doing it later
Tips & Tricks for documentation - discussed yesterday, e.g. first person to encourage people to try things out/be experimental
We'd like to put together a document, ideally not too long!
• The format is not as important as the content! The tool won't fix it for you, ultimately you need to write something clearly and the tool will help you.
• Is it possible to document something when you build it first?
○ You can use git for that, make a lab notebook and track your progress over some days. That's not the final documentation though.
○ Taking photos as you go is really helpful!
○ Videos too! That's a requirement on Daniel's students' project courses
§ Videos are helpful but not sufficient to replace other documentation
§ They can be really helpful for tricky steps
§ IT's just a record, you need other stuff too
○ There's two aspects here; formal, condensed assembly instructions and informal logs/accounts of an experiment. Both are important!
○ It's important to document stuff that doesn't work
○ If you want to make good instructions, you need to do more than just take photos as you go along!
Tobey's prepared some stuff already, the document will be linked to from the forum. Reference some existing guides: OSHWA best practice guide, GOSH 2016, JOH guide Licensing is also important, should connect to the licensing workshop to add in their guidelines here.
We started by talking through the guidelines in the Google doc.
Mentioned OSHWA certification (which is legally enforcable) - does that stop you closing it up?
What about the data?
How dynamic is the certification? - it's self-certification so you can do it as you go along.
- it's also not a license; you need to choose a license.
Certification covers "hardware projects must…"
Journal covers "hardware projects should…"
Choice of channel - e.g. HardwareX is controlled by Elsevier...?
We then discussed a bit about the scientific publishing scene, and whether academics are really "volunteering" when they review/serve as editors (they are not paid by the journal, but their institutions pay them and the publication system is part of their jobs).