A design document is a way to communicate to others what the intent behind a certain feature/solution is. In the Apollo community we use them to facilitate discussions and reach agreement about important design decisions.
Design docs are written with the purpose of helping community members and contributors understand design proposals and judge them on their merits.
A good design document should:
- state the problem that is being solved as clearly as possible
- explain why the problem should be solved in this package, and not a different one (or possibly a new one)
- show that the proposed solution fits in with the stated vision for Apollo Client
- incrementally adoptable
- universally compatible
- easy to understand and use
- compare the proposed solution with obvious alternatives and show that
- the proposed solution is better than its alternatives with respect to the Apollo vision.
For an example of a design doc, see Apollo Errors.