[DEV] Fighting the Details on the Way to Simplicity | The Neurons Fire | The Efficiency of Chief Roles
This here is kind of an insight into development, so you can see how much effort it can be to fix just a few details in a product and its documentation
You may have noticed this one here:
which resulted in this TASK issue:
README, First Pass
The first pass was quite easy. Here is the A / B comparison of the REAMDE
The original README has 16 contributors and was a bit messy, the revised README starts(!) to have my personal "style" (still too large/complex for my taste). Personally, I believe that good documentation results out of "ownership". An owner has a style, a (partially artistic) flow, and should be able to "create in peace" (e.g. the evolving docs are not changed when the owner 'digests' in order to apply the next steps). And an owner can be blamed nicely for docs being bad.
Latest Stable Version
Further simplification depends on a tiny reorganization of the project. The first try here:
I aligned the "Install from Source" part of the README to the Official Cardano Shelly Testnet Documentation . This docu install from the master-branch.
To avoid things "getting too much discussions", I pointed out the most important things, and closed the PR, waiting now for the fulfillment of this issue:
Having a "stable" branch is more or less "Standard-Procedure".
This is out of my reach (cannot solve it myself). Once done, the show goes on.
Once this is done, a rule should be extracted, in order to make this construct mandatory in the overall IOHK/Cardano system (e.g. all repos must have a deployable dev-branch "master" (should be already the case), and must have the latest stable release available within branch "stable" )
I usually identify weaknesses and flaws in subseconds, the same is true for identifying necessary steps towards simplification/clarification. "The Neurons Fire", I don't even need to think mostly. A natural ability, additionally trained in the IT domain over decades whilst analyzing weaknesses and failures of hundred if not thousands of products and projects. This woks within code, too.
Most of the above REAME related changes came up immediately – but then, explaining, documenting etc. takes hours if not days.
Why do I mention this?
Because it is a total waste to not have this talent in a Chief role, where one can perform without barriers, until fired because of mess.
A cold-induced head-ache reminds me about reality.
Time to wake-up!
 (those docs are a tiny drama in itself. It needs much simplification/clarification, but this comes to a later point.)