I'll chime in: Mike Hearn is absolutely right.
There's nothing wrong with writing "documentation" to help describe at a higher level what is going on. As a developer of a non-validation client, such documentation has been quite useful. I fully support "extra stuff the describes at a high level what's going on". But you must understand that once you put the word "specification" on any such document, you are promising the reader that the document is sufficient for creating a compliant implementation of what is being described. But, anything short of the source code itself is not sufficient for implementing it. And worse, the consequences of not doing so will result in people losing money -- because if there's an inefficiency in the system an attacker will exploit it, guaranteed (especially one where your target uses code that validates differently than much of the rest of the network). This is why Satoshi did not support alternative implementations.
Write all the "documentation" you want, and put as many comments into the code as you want. But do not use the word "specification" because nothing except the code can qualify for it.
+1There's nothing wrong with writing "documentation" to help describe at a higher level what is going on. As a developer of a non-validation client, such documentation has been quite useful. I fully support "extra stuff the describes at a high level what's going on". But you must understand that once you put the word "specification" on any such document, you are promising the reader that the document is sufficient for creating a compliant implementation of what is being described. But, anything short of the source code itself is not sufficient for implementing it. And worse, the consequences of not doing so will result in people losing money -- because if there's an inefficiency in the system an attacker will exploit it, guaranteed (especially one where your target uses code that validates differently than much of the rest of the network). This is why Satoshi did not support alternative implementations.
Write all the "documentation" you want, and put as many comments into the code as you want. But do not use the word "specification" because nothing except the code can qualify for it.
low level detailed documentation is useless and could be dangerous. but a high level diagram can be very useful for a quick refresher as to how a particular module dose what it dose, and more importantly, when your talking to someone about making changes a good diagram will felicitate communicating ideas.
