4.1. Accessible docs
This is a template module
- Make it easier for the reader
- Identifying required skills
- Audiovisual formats in documentation
- Assignment: Improve your documentation
- Resources
Make it easier for the reader
The same guidelines used to describe your project to people seeing it for the first time apply to the documentation of your project:
Different people will have different interests in your project. Some might just want to use what you are developing (and they may or may not have previous skills in building open hardware). Some people might want to join efforts in developing with you, some might want to build a derivative of your work, using it as a starting point for something new.
Just from these three examples, we can imagine that we need to cover different aspects of our project. How can I guide people to build my hardware? How can I guide people to use it? How can I make co-development easier by setting out clear explanations on what is the expected way to work together?
People reading it will have different skill levels and should not have to spend a lot of time looking for the meaning of a certain jargon or words they never saw before. Think broadly, can a person who has never build anything build and use this? Can an expert do the same?
A good approach to document things is to split it into to different documents each focused on one use case. This allows documenting to be more tractable and facilitates reading/watching. One suggestion would be to develop one document for using your hardware, one for building/assembling it and one for developing it.
Identifying required skills
When documenting a project it is normal to focus on the bits and pieces that go in it, and show the steps to put them together. However, it is also important to make sure people know what are the tools they need to put parts together, as well as what skills are necessary. It is a bit frustrating to be in the middle of a build and realize that you don’t have that one screwdriver needed to fix two pieces together, or that you should brush up on your soldering skills.
That’s why you should make sure to have a list of necessary tools and skills needed to develop/build your project together with your documentation. They go quite nicely with the bill of materials.
Audiovisual formats in documentation
Another way to document your project is to make a video as you build it, as this is a more organic way of explaining to others what is going on, and how the build/development progress.
One point to watch out for is that it can be cumbersome to find a specific bit of a video, when a certain instruction was given. Therefore, make sure you make marks (timestamps) on your video that enable viewers an easy way to jump back and forward, checking/rechecking different steps.
A nice thing about videos, is that they have several different subtitles, so with one recording, you can reach many different groups that speak different languages. For that to work great, make sure you note down somewhere that you are looking for collaborators to translate your videos and make sure they have an easy way to edit subtitle files.
Assignment: Improve your documentation
- Revisit your contribution guidelines and documentation plan
- In previous modules you worked on your documentation plan. You can now work on adding content to that plan, check if it is useful or if it needs changes. Doesn’t matter if you can’t have a polished version right now, but add as much detail as possible to your documentation considering users (using and assembling) and developers (contributing).
Resources
Beginner guide to docs Examples of technical documentation
next: Bill of materials