Design Document (Again)
The point of a design document is to design the package and document
the design. It is not like a textbook and not like a journal article.
Background not relevant to the computer implementation is not necessary.
Relevant background is necessary. You are not going to publish this
document, but it should go in the inst/doc directory of the
package. This is in addition to the package vignette, which also goes there.
This document has only two intended readers. You (it helps you think — what you can't explain in the design document, you probably can't implement correctly — it's easier to write correct equations than correct code) and any future implementer of your package (which may be you two years from now when you've forgotten all the details of what you did). It also has me as a reader, but I'm reading it from the viewpoint of an implementer.
If you want to see an example of what I am talking about, the trust package has such a design document.
Note- It doesn't worry about most things the 2 textbooks cited are worried about. No proofs. No background.
- It does worry about many things the 2 textbooks don't.
- It worries about numerical stability, divide by zero (and by very small quantities that may be zero plus inexact arithmetic errors).
- It worries about the order of operations.
- It worries about termination criteria.
All issues are clearly (I hope) explained and reasons for the choices
given. If someone wanted to take over the development of the trust package,
they wouldn't have to read the code constantly muttering What could
this idiot have been thinking?
.
Note that the person muttering about idiots could be your older wiser self months or years later.
Also note that many bad ideas were rejected during the writing of the design document before I wrote a line of code. (I probably did revise some as code was written and I realized new issues, but I stopped writing code while I revised the design document.)
It's always a bad mistake to try to think and write code at the same time. Think while writing the design document. Then code. If you need to stop to think, then you probably need to revise your design document.
