I'm also concerned with needing to refer to the reference client source code but the reference client is called reference for a reason
My concerns are that as the reference client struggles to stay relevant for end users the core developers focus on performance rather than for use as a reference.
Performance and readability do not tend to go hand in hand.
Is the creation of better protocol documentation a better solution?
I personally think so, as the core aspects of the protocol are effectively set in stone we should be able to document them in an accessible/understandable manner.
As Gavin identified the creation and maintenance of specs however is time consuming.
The reference client developers are free to spend there time however they feel is best. There are always issues to be fixed and new features to be implemented. We wouldn't want to stop the reference client from moving forward.
I'd like to offer my help in updating/maintaining the documentation. I've made a few minor edits to the Bitcoin wiki for some of the under specified or unclear areas that I've found.
Where do you feel the content of the Wiki currently falls short?
In my experience I've found that the status of some of the BIPs are out of date and I've tracked a few of them down and updated their status.
Once a BIP is accepted I think we should aim to roll its implications into the base documentation.
This information is recoverable by comparing the reference implementation to the BIPs.
In what ways do you feel that the Reference client falls short as use as a reference?
In my experience something the reference client does not capture well are the "gotchas" that have been solved over time that are relevant to all Bitcoin peer implementations.
When reading the reference code you might not realize that a piece of code evolved to its current state to solve a serious issue and that the naive implementation wouldn't be sufficient.
Again this information isn't lost we can recover it from the history and issue tracker and present it in a more accessible way.