A developer handbook is indispensible if you need to remember what you did a year ago (due to a bug or a new feature to be added) or if you want to bring a junior developer up to speed without baby sitting him. A good handbook should include the following:
- Introduction: Why does the system exist, what function does it serve?
- Components of the system, how they communicate with each other (serial, ethernet etc.). Photos of the real system and a mind map denoting peripherals (sensors, actuators) would be handy:
- Setup: All software and hardware setup procedures, links to software installation folders.
- Sanity tests to verify that setup works properly. For example, have a test to verify that the system really works in real time by comparing system time with an external time source. A very crude test would be using the timer in your smartphone.
- Development use cases: How to add a new state to the state machine.
- Design:
- Architecture.
- Main workflow, especially external input/output.
- Task priorities and rationale.
- Design decisions and their reasons. Why is the current design the best one under existing constraints (time, budget, experience)? Why is there no simpler way to satisfy requirements? What were the disadvantages of the alternatives. Examples: Why did you write your own file transfer protocol instead of using an existing one? Why have you not used an OS like VxWorks but choose Micrium? Couldn't you have done it without an OS?
- Troubleshooting guide for frequent problems.
No comments:
Post a Comment