It seems like the basic instructions in the README are pretty good. What I think would be most helpful would be some more examples, and some discussion of what afew is good at, and what it's not.
I disagree with "the instructions in the README are pretty good".
Take for example:
What exactly is "basic tagging stuff"? I have no idea what that means. Why would I even run that command? notmuch automatically adds a tag for new messages. What exactly does afew do different? Or on top of that? I don’t know.
Also, based on reading the user manual, it seems that there is a default spamfilter. How can I turn that off? I already have spam filtering in a different place in my mail infrastructure.
I found afew via https://notmuchmail.org/initial_tagging/ which directly links to the repo. Then I was struggling to understand the main README.rst because (as discussed in this issue) it left some open questions.
But then I found the more extensive documentation in the docs folder respectively at https://afew.readthedocs.io/en/latest/ and that was good enough.
I suggest to shorten the main README.rst so that it doesn't duplicate information from the full documentation (basically just leaving a summary and a link) and then close this issue. Agreed? I can prepare a PR.
The instructions in README.rst duplicated some of the information in the more complete docs, but not enough to really get started using afew. It is better to avoid duplication and refer new users directly to the full documentation. The README.rst installation instructions were slightly more complete and recent, so they were copied to the docs/sources/installation.rst. While at it, fix broken links in the rst markup. Fixes: afewmail/afew/afewmail#23.