Session Title:Documentation and Sharing
Date:24/03/2017
Attendees (who was there?):
Overview of topic (3-6 sentences):
Notes: https://docs.google.com/document/d/10SQT6jdUCAM-oCTE3ou5C9eDSO5IuFu8j1-1R_kvxAk/edit?usp=sharing
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
Richard -
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).
1 Like
hI Spain initiativrs has a kind of tutorials How to Do , not is focused en Science but can be of interes of some one http://laaventuradeaprender.educalab.es/guias
1 Like
Types of documentation
We need different things at different stages of a project, and for different users. A project’s documentation consists of a number of types of information, and it’s important to think about them all.
Log/blog
Informal, non-edited accounts of what you’ve done - design thoughs, a construction, testing. In a science lab, this is your lab book. Write in first person, use lots of pictures, videos, and informal commentry. Don’t worry about neatness or formality. This should be shared with the project - ideally somewhere open. Comments and collaboration are good here - but let’s keep it informal, or it will become a huge drain on everyone’s time and energy!
Assembly Instructions
Concise, carefully edited instructions allowing someone to reproduce your hardware. This needs to be full enough to stand on its own, but must also be concise enough to be approachable and not scare people off. Most likely, the assembly instructions are edited and re-worked many times to make them clear and concise. Probably, these are versioned together with the other design files.
User Manual
Once you’ve built the hardware, you need instructions to use it; like the assembly instructions, these will need to be edited and improved collaboratively.
Design Rationale
A longer document/metadata attached to instructions, explaining why the hardware is designed the way it is. Probably this contains edited, improved versions of the thought processes that were captured in the log/blog. It might even follow a similar structure to the assembly instructions and/or user manual, or be embedded within them.
A note on wikis
This can be a great way to collaborate on edited documents (this could be design rationale, or even bits of the manual or the assembly instructions). However, it tends to take on an authoritative tone - appropriate for the assembly instructions/user manual/design documentation, but also it can discourage participation - so somewhere for first-person comments or chat is important. Doran (Farm Tech) mentioned they’re trialling a wiki-with-first-person-comments system, to try and address this.
2 Likes