Hardware Reference
In-Depth Information
An example of source files, README.txt, assembly instructions, and images for the
Blinky Buildings kit associated with this topic can be found at
http://bit.ly/blinkybuild-
README.txt
The README.txt, or in some cases the product homepage, introduces the hardware
throughdocumentation. Beginningdevelopers ofopenhardwareprojectsoftenrelyondoc-
umentation the most heavily. The landing page of your project, whether it consists of a
website or a text file, is the place you want to provide an overview identifying the follow-
ing items:
The project
Licenses
Attribution
Expected time to build it
Cost
Expertise level
I like to think of the landing page as a quick summary of what people can expect and
attempt to answer questions before they ask them. The introduction, or README text,
not only gives an overview of the project, but also carefully leads developers into the pro-
ject's build structure. It's important that these instructions are summarized as clearly as
possible. I like to also note the last time the documentation was updated, as a reference for
people who are unfamiliar with the project or who are unsure how up-to-date the informa-
tion is. This item can be as simple as a small notation at the bottom of the webpage.
The README.txt should also include licenses and attribution information, which can
sometimes go hand in hand. For example, SparkFun's README.txt (
Figure 14.1
) for the
Arduino Pro Mini includes a CC-SA license, attribution to the original Arduino Team, at-
tribution for the Pro Mini, and attribution for revisions made to the board. This file is also
a good place to record any warranty information, although you may also want to include
warranty information on the product packaging.
