Hardware Reference
In-Depth Information
partial description (e.g., you know you need a magnet, but maybe not which one),
put them on the BOM and leave the part number blank. Then keep the BOM handy
while you are shopping and fill in the blanks as you make your purchases. It is
much easier to add to and modify existing documentation as you work through the
design and testing of a project than it is to create all of the documentation at the
end from memory or random notes.
3.
Document as you act.
So you saw and followed Rule 2. Good. But you aren't done: you must also docu-
ment as you act. Take pictures of each and every step as you build and test proto-
types. For this process-oriented documentation, a cellphone camera is perfectly
fine. Capturing some detail about every step and doing so easily is far more import-
ant than capturing specific steps in excruciating detail. And photos aren't the only
thing you need to capture. Take notes (public notes are best, but handwritten or
even—gasp—private notes are acceptable as long as you make sure to record them
publicly shortly thereafter). The Shepard team uses Open Design Engine's News
module to record development logs. These development logs are essential to keep-
ing the team and the public informed about the progress and changes in Shepard
projects. Such development logs also provide a reference from which more formal
documentation can be written and allow anyone following the bleeding edge of the
project to replicate your work.
For those developers who think only the final documentation counts, consider
this. Presenting a project as a fait accompli blunts two of the major advantages of
open source methods: contributions from volunteers and the educational benefits
of open source methods. Without up-to-date documentation, potential contributors
cannot follow along and offer up their own ideas or make other contributions, be-
cause they have no way to know about the design or the work that needs doing.
Similarly, the opportunity to explore the full history of a project makes it possible
to learn lessons from the project team about what does and does not work (in terms
of design and process).
4.
Document after you act.
This is the one documentation ground rule everyone knows. In fact, they usually
assume it is the only one, making it a huge chore to satisfy. If you follow Rules 2
and 3, however, documenting after you act becomes more about formatting and
editing. In addition, creating final documentation from draft documentation is
something that can be done by a group of people (unlike documenting exactly what
you spent all afternoon doing), giving your entire project team and community a
way to help out with the documentation.
