README.md distillation #114
Conversation
README.md
Outdated
|
|
||
| CadenceBot is fully featured, and is functionally equivalent to the [web client](http://cadenceradio.com/). You can add CadenceBot to your Discord server by clicking [this link.](https://discord.com/api/oauth2/authorize?client_id=372999377569972224&permissions=274881252352&scope=bot) | ||
| It allows you to control your station through a Discord server and even listen to the radio in voice channels! CadenceBot is fully featured and functionally equivalent to the [web client](http://cadenceradio.com/). |
There was a problem hiding this comment.
Should we even go a step further and remove "...fully featured and functionally equivalent to the web client"?
This part of the readme was very much written towards the vision of it as a tech demo when the bot first came into being, with you (@kenellorando) in mind as the reader seeing what's been added - Since we're taking the step of moving it towards being for 'end-users', perhaps that content is no longer required at all.
|
|
||
|  | ||
| 1. [Get your token from Discord](https://github.com/reactiflux/discord-irc/wiki/Creating-a-discord-bot-&-getting-a-token) and save it somewhere. | ||
| 2. Run the script `first-time-setup.sh`. This will prompt you for an (optional) email to deliver bot logs to and the Discord token you saved in the previous step. |
There was a problem hiding this comment.
I like these simple steps, though frankly with #105 open I was just going to delay writing things this way until it was fully recreated.
If we're going to leave the readme in this state for the time being though, we should probably at least document what this setup process requires - Namely, that you're running on some sort of platform where apt is the package manager (technically not necessarily Linux, though I'm not aware of other platforms that fit that criteria)
|
|
||
| Separately, CadenceBot subscribes to Discord to receive messages invoking commands, and therefore also sends messages back to Discord as part of user interaction. | ||
| </details> | ||
| - See all alternative installation methods on [Installation Guide]. |
There was a problem hiding this comment.
This feels like a wiki page, to be sure.
|
|
||
| Now, CadenceBot should run properly, even if a change requires a new module or new module version. There is only one detail left - When CadenceBot is restarted by the `restart.sh` script, it keeps its log in the `CadenceBot.log` file, which is overwritten each time the script is run. If this is not desired, you can make a `maillog.sh` script, which shall be run before starting the bot each time `restart.sh` is run, with the intention of being used to archive the log before it is deleted (by email, usually). Add whichever commands you would like to this script to have your logs archived automatically. | ||
| </details> | ||
| ## Implementation Details |
There was a problem hiding this comment.
This feels like it could work at the end of the README, as a "You no longer care if you're just doing setup, you can read this part if you're looking for it instead of linking out"
To me, at least - I'm open to other opinions.
README.md
Outdated
| - Prompt you to review the changes before pushing them to `master`. | ||
|
|
||
| Note that the script does not apply any sort of validation or sanity check to the passed version number at this time: It is up to you, as maintainer, to validate that the version number is correctly formatted, is newer than existing version numbers, and has proper scope. | ||
| - See all development notes on [Development Guide]. |
README.md
Outdated
|
|
||
| ## Implementation and details | ||
|  |
There was a problem hiding this comment.
Is it worth keeping this screenshot in-repo like I did with the diagrams?
Probably not, it's a pretty interchangeable image, but have I established a "convention" by doing so with the SVGs that should now get followed?
|
|
||
| CadenceBot is fully featured, and is functionally equivalent to the [web client](http://cadenceradio.com/). You can add CadenceBot to your Discord server by clicking [this link.](https://discord.com/api/oauth2/authorize?client_id=372999377569972224&permissions=274881252352&scope=bot) |
There was a problem hiding this comment.
Should we keep the "You can add CadenceBot by clicking this link" bit? I think that's probably helpful for people a layer below wanting to dive right into being an IA - There's really nowhere else where we give the opportunity to add prod CadenceBot, so if we ditch this link we need to either find a better place to keep it or we're essentially saying "Don't use prod CadenceBot, you must deploy your own for your server" - Which I don't think is what we actually want to communicate.
There was a problem hiding this comment.
@za419 This would only add a bot configured with cadenceradio.com itself, correct? Maybe it would make sense if I added it as a "try it out immediately" one-click kind of thing.
There was a problem hiding this comment.
Correct. That's the same prod bot that we've been using. I agree with it as a one-click try-it-out thing - My logic basically sums up to "More people are more likely to want to use a bot than run it"...
Plus, it's a good demo. Probably people want to see the bot in action before committing to hosting and IA-ing a copy...
|
The latest update adds the implementation and development details back in, in |
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.