- snip -
At any rate, the view that bitcoind source should be the documentation is not very helpful for the future development of the network. And to say there should be no good documentation doesn't really hold up in argument. One could argue that Bitcoin should be the best documented piece of software on the planet.
You are welcome to write any documentation that you like.
The thing to keep in mind is that any written protocol is an attempt to describe what the reference client already does (including any "bugs" or unexpected behavior). The reference client is not written to implement a specific written protocol.
As such, if there is any discrepancy at all between what is written in the documentation and what the reference client actually does, then the bug is in the written documentation, not in the reference client. The written documentation will in that case have failed to properly describe the protocol.
This means that no developer can depend on the written documentation as a definitive description of intended (or actual) behavior. As such, while the written documentation can be useful as a reference and as educational material for getting started, it is useless as a specification for exact behavior.