README update #2824
README update #2824
Conversation
* highlight readthedocs as main way to get started * separate out installing the current release from using pre-trained models on master * based on my experience here: https://discourse.mozilla.org/t/installing-deep-speech-for-the-first-time-thinking-out-loud
No Taskcluster jobs started for this pull requestThe `allowPullRequests` configuration for this repository (in `.taskcluster.yml` on the
default branch) does not allow starting tasks for this pull request. |
| # Install DeepSpeech | ||
| pip3 install deepspeech | ||
|
|
||
| If you're using the **MASTER version** of DeepSpeech, you can get started using a pre-trained model: |
There was a problem hiding this comment.
This seems to imply that there exists a pre-trained model for the MASTER version which is not the case.
There was a problem hiding this comment.
Yeah, I wasn't sure what to do with this part. We could either:
- delete these instructions
- reword to "If you're using the MASTER version of DeepSpeech, here is the syntax for using a pre-trained model:"
There was a problem hiding this comment.
To me this seems more confusing than it was at the start.
Now this documentation has to juggle two versions of the code. Where previously it had a big warning that said go to readthedocs for the latest stable version, otherwise stay here for Master.
There was a problem hiding this comment.
Thanks Kelly - I'm trying to wrap my head around why this block of code exists? It mixes installing the stable version, using 0.6.1 models, and master syntax. When will someone be able to run this code?
I'm trying to separate it out into chunks that are usable, but that seems to be creating its own problems.
There was a problem hiding this comment.
When will someone be able to run this code?
This is accurate at release time.
There was a problem hiding this comment.
@acabunoc Did you tripped over this because of the amount of docs, or because it's unclear, or because of something else ?
There was a problem hiding this comment.
Thanks for asking @lissyx --
I made the assumption that the first block of code on your landing page would be a good place to get started. I understand that there are instructions to look elsewhere, and I eventually saw that and moved to the docs. However, I will not be the only person making this assumption. Most thriving open source projects will have a usable block of code on their landing page, if they have code there. I'd love to see more developers stepping into this project and immediately feeling comfortable.
Tiny changes like this can make a huge different in community engagement and go long way to show new contributors that their presence is welcome here.
There was a problem hiding this comment.
Most thriving open source projects will have a usable block of code on their landing page, if they have code there. I'd love to see more developers stepping into this project and immediately feeling comfortable.
Well, I share that. At the same time, everytime I'm looking at some docs from a master branch, I know it might fail, and if it does, I look for something that is stable.
I think we all on the team assumed this was the default behavior of people. Is this wrong ? Do people don't care about matching-version documentations ?
I don't see how we can ensure and provide always-working master branch + instructions, especially given a release is made when a new model is ready.
I made the assumption that the first block of code on your landing page would be a good place to get started. I understand that there are instructions to look elsewhere, and I eventually saw that and moved to the docs.
The obvious solution would be to keep "stable" instructions on top, but then it is also confusing to people in other ways. And it's also going to be much more messy to mix.
I honestly have no idea how we can fix everything at once.
There was a problem hiding this comment.
We don't provide always working master branch instructions. As it is, our master branch is wrong most of the time. It's only correct in the time between a stable release and the first breaking change. As far as I can see, the only benefit our policy brings is to reduce the number of changes we have to do at release time (just update the model URL). Personally I'm fine with leaving the master instructions matching the latest stable release.
Another possibility is to create release branches in addition to release tags, and then switching the GitHub default branch after a release. That way when users come to the repo the stable instructions are shown, and we make it so that only contributors need to do the extra work of switching versions. I guess people who know enough to change the code and send PRs also know enough that changing versions won't be a hassle.
There was a problem hiding this comment.
Thanks both!
Well, I share that. At the same time, everytime I'm looking at some docs from a master branch, I know it might fail, and if it does, I look for something that is stable.
I think we all on the team assumed this was the default behavior of people. Is this wrong ? Do people don't care about matching-version documentations ?
In many cases, I think you're right. But this is also the main landing page for your project -- not just some docs. Small barriers here can signal that that you have your own short-hand on how you work as a team & you're not ready for outside contributors.
I agree that people experienced in open source & code can easily get over this. But I would hope that this project could be welcoming to more than the existing open source crowd (which has its own diversity problems).
@reuben - huge thanks for bringing up a couple solutions. Both are great. The team knows more about your workflow/community to know what would work best here. Let me know if I can help at all.
lissyx
added
documentation
waiting-on-reporter
|
@acabunoc I just landed a pull request slimming down the GitHub README to point people to readthedocs.io, which contains versioned documentation and by default shows docs for the latest stable release. I've also moved the demo section from the README into the readthedocs index page: https://deepspeech.readthedocs.io/en/master/ |
|
Huge thanks @reuben! I'll go ahead and close this. |
I took some inspiration from the tensorflow readme to:
Based on my experience and feedback here: https://discourse.mozilla.org/t/installing-deep-speech-for-the-first-time-thinking-out-loud