CapitainFlam commented 1 year ago

TL;DR: the readme file is harsh for newcomers, it's lacking an oversimplified overview of WTF is doing sentence-collector and in what order.

Lowering the barrier for understanding the project shall help people to come. I hope. ...And even if not, ME, I need this stuff to be written down, to be clarified and to be understandable for a dummy like me.

After (trying to) work on the PR https://github.com/common-voice/sentence-collector/pull/635 (full disclosure : I started it 😸), I am now convinced that something is missing in the introduction of the sentence collector [README.md](https://github.com/common-voice/sentence-collector#readme) file.

Let me explain in two words.

GLOBALLY (as discussed in an other FR discussion and/or issue) we have Sentence-collector > recording & review > CorporaCreator

LOCALLY, I was thinking that thes steps were Import start > Cleanup > Validation > Add it Common Voice database ready for recording & review. And it seems that the steps are Import start > Validation > Cleanup > Add it Common Voice database ready for recording & review. . There is a discussion here (sentence-collector-cleanup-before-export-vs-cleanup-on-upload/105411) that seems to discuss this point... In short, I'm lost.

So, MY PROPOSAL IS :

to add a little paragraph right before Get Involved saying :

Common Voice Sentence Collector

The Sentence Collector is part of the Common Voice project. Its purpose is to provide a tool for contributors to upload public domain sentences, which then can get reviewed and are exported to the Common Voice database. Once imported they will show up for contributors on Common Voice to read out aloud.

Quick overview

Sentence-collector is the "entry point" for data to be recorded and reviewed. Then, once ready, it will go to CorporaCreator.

Under the hood, Sentence-collector work like this (oversimplified version) :

You take a buch of sentence you want to add the the database (as explained here),
then it's cleaned up,
after, it's validated,
and finally sent to the text database for recording & review.

We can always go deeper in documentation in common-voice docs.

Get involved

(...)

CapitainFlam commented 1 year ago

Might be impacted by : https://discourse.mozilla.org/t/sentence-collector-cleanup-before-export-vs-cleanup-on-upload/105411/9

MichaelKohler commented 1 year ago

:tada: This issue has been resolved in version 2.18.2 :tada:

The release is available on GitHub release

Your semantic-release bot :package::rocket: