I argue that a new user's number one desire is easy installation. I've realized that what most users solely care about is how to "use" the project. They want to derive value as fast and as easily as possible. To do this, they'll take ten seconds skimming the README to get a feeling of how much time it would take to do it.
@za419's latest change to the README was a definite improvement, especially with the addition of some new illustrations. CadenceBot isn't actually complex to install at all, but I think the remaining text still makes it look daunting. If our goal is to onboard more users, we should distill as purely as possible to what the installing user needs to know. We should classify everything else as non-essential to the first-time user and move it to the GitHub Wiki.
I took these principles from Cadence's repo and applied them here:
Emphasis on how to start immediately. The first section is how to install. The installation section should give the user the impression that it would take little effort to get started.
Remove any technical explanation of what anything does in the background unless necessary, and provide a link to deeper documentation if the user desires to read it.
Remove most "optional" and all "non-recommended" steps and method text, on the same principle.
Add a photo of the bot itself in operation. The illustrations so far are good but people like to visualize the end-product. I just took the one in this PR on a whim, so @za419 can change to whatever he sees as the best representation of CadenceBot.
If acceptable, I expect @za419 to make additional changes as he sees fit. I might have messed up some of the steps or distilled too much. Merging of this PR would also require any "removals" to be migrated by @za419 into another documentation location, and to fill in the empty URL links that I suggested in square brackets.
This PR changes the README.
I argue that a new user's number one desire is easy installation. I've realized that what most users solely care about is how to "use" the project. They want to derive value as fast and as easily as possible. To do this, they'll take ten seconds skimming the README to get a feeling of how much time it would take to do it.
@za419's latest change to the README was a definite improvement, especially with the addition of some new illustrations. CadenceBot isn't actually complex to install at all, but I think the remaining text still makes it look daunting. If our goal is to onboard more users, we should distill as purely as possible to what the installing user needs to know. We should classify everything else as non-essential to the first-time user and move it to the GitHub Wiki.
I took these principles from Cadence's repo and applied them here:
If acceptable, I expect @za419 to make additional changes as he sees fit. I might have messed up some of the steps or distilled too much. Merging of this PR would also require any "removals" to be migrated by @za419 into another documentation location, and to fill in the empty URL links that I suggested in square brackets.