Documenting a project is the goal of design, not an artifact… not a struggle to complete during the project and regretfully past the last design review and after it is shipping. Documentation is the design. It is the result. It is the artifact.
Although many fret with this activity and postpone it to the end, or denigrate it to the last priority it should be the first. This is where knowledge and advancement is embodied – NOT in the minds of the creator. Let me be very clear on this point. The documentation is the goal.
Now when we consider a hobby project, or a project of an individual researcher or inventor, what is sufficiency as there are different standards depending on the type of company and the scale of deployment.
There are classifications of the components of a design that can be helpful in this discussion. For example, how can we decompose a design? Over functions? Over Times? Over Stages? Over levels of complexity/systems? Separate HW from HW.
This can only be answered by the answer to this deeper question. What is the lasting benefit of documentation? For individual experimentialist projects, which is the category I inhabit, this is very useful – skillful even.
For us, at this point in time (salaried man, with 4 hours a week of time available to experimentation) the primary benefit of documentation is the ability to immediately pick up what I was dong last, and resume from exactly the same place, but this time rested and armed with a set of ideas on how to confront the challenge ahead.
This kind of documentation is SO much more useful because you only document what you will find immediate utility as opposed to patents, where your goal is to map out an entire universe where this new idea si not only prohibited,but morally bad for you.
1. Can I resume where I left off when I shut off the power yesterday (or when I was experimenting last)?
2. Will the system behaved the same way as it did when I last encountered it? This is VERY important. We should be able to document a system so that when we return or repeat the initial conditions, we get exactly the same output!
Software: Current source file, with name and date. Have this displayed during wakeup of embedded device. Location and computer should be listed. The source code should be printed out.
Platform: The HW platform should be noted, including revision number, and special characteristics (like Arduino UNO SMD, Rev 3). Where possible an image of the platform should be captured as a photograph.
Components: Document a bill of components, noting source and version number or distinguishing type (often very important). Include pinouts of components, and any important parameters.
Schematic: Draw the schematic in any form.
Layout: Capture the physical design and arrangement of the components.
Notes: Describe any additional documentation that might be helpful including reference web sites, notes about operation, changes required/warnings/guidelines.
MetaData: Finally, this file should be easy to find. It should be printed out, indexed/filed in a convenient place, and put away. There should be a pointer from the physical device to the documentation.