Code Is Documentation?
I am considering running a Steem witness node. So I did a Google search for "howto run a steemit witness node" (without the quotes), and the first result was @pfunk's A Full Steemit User's Guide to Steem Witnesses. There's plenty more to read before I attempt to setup a node, but this article is not about that.
In looking at the README for the node code, I was struck by the claim there that "Code is Documentation". Really?
Having made my living writing code for most of the past nearly 40 years, I realize that the code is the only real documentation. Only the code says what the code will truly do. But that doesn't absolve programmers from writing documentation, to help others understand the code. A month after you've stopped looking at a code base, you are part of that crowd of others.
Not much to be done here, I'm afraid, except what you can do about any open source project you want to improve, write that documentation myself. I guess, should I decide to proceed with running a witness node, that will be one of my preparatory tasks. I hope that whoever authored that paragraph does not believe it so ferverently that they will refuse to approve a pull request including documentation. The paragraph was included in the initial README in the "Initial Checkin", which was committed by revflash (steemit account unknown) back in March of 2016. @proskynneo (github: mvandeberg) has been more active recently. Though there have been a few other contributors, e.g. @theoreticalbts, those two have made the bulk of the contributions.
It appears that @theoretical has written a series of posts about the internals of the Steem blockchain. More for my reading list.
Simply Great Information and Presentation