write documentation #23

Closed
teythoon opened this Issue Dec 24, 2011 · 9 comments

Comments

Projects
None yet
7 participants
@teythoon
Collaborator

teythoon commented Dec 24, 2011

No description provided.

@ghost ghost assigned teythoon Dec 24, 2011

@nickurak

This comment has been minimized.

Show comment
Hide comment
@nickurak

nickurak Jan 22, 2012

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.

Examples:

  • How to set up spam auto-tagging
  • How to set up mailing-list auto-tagging

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.

Examples:

  • How to set up spam auto-tagging
  • How to set up mailing-list auto-tagging
@stapelberg

This comment has been minimized.

Show comment
Hide comment
@stapelberg

stapelberg Apr 15, 2012

I disagree with "the instructions in the README are pretty good".

Take for example:

Basic tagging stuff requires no configuration, just run
$ afew --tag --new

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 disagree with "the instructions in the README are pretty good".

Take for example:

Basic tagging stuff requires no configuration, just run
$ afew --tag --new

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.

@teythoon

This comment has been minimized.

Show comment
Hide comment
@teythoon

teythoon Apr 16, 2012

Collaborator

@mstap: Agreed, the current documentation is not sufficient, especially for new users.

Collaborator

teythoon commented Apr 16, 2012

@mstap: Agreed, the current documentation is not sufficient, especially for new users.

@albins

This comment has been minimized.

Show comment
Hide comment
@albins

albins Jul 7, 2012

I agree. What I'd like to see is primarily how to define your own filters, which I (after several hours of frantic googling) still don't think I've quite figured out.

albins commented Jul 7, 2012

I agree. What I'd like to see is primarily how to define your own filters, which I (after several hours of frantic googling) still don't think I've quite figured out.

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Jul 17, 2013

What documentation is needed? It would be helpful to have issues for the different places that need more documentation.

ghost commented Jul 17, 2013

What documentation is needed? It would be helpful to have issues for the different places that need more documentation.

@lucc

This comment has been minimized.

Show comment
Hide comment
@lucc

lucc Apr 6, 2016

Contributor

Any news on this? What can people besides @teythoon do to work on this issue?

Contributor

lucc commented Apr 6, 2016

Any news on this? What can people besides @teythoon do to work on this issue?

@ghost

This comment has been minimized.

Show comment
Hide comment
@ghost

ghost Apr 6, 2016

No one.

ghost commented Apr 6, 2016

No one.

@flokli flokli removed this from the release 1.1 milestone Jun 19, 2017

@pohly

This comment has been minimized.

Show comment
Hide comment
@pohly

pohly Apr 10, 2018

Contributor

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.

Contributor

pohly commented Apr 10, 2018

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.

@flokli

This comment has been minimized.

Show comment
Hide comment
@flokli

flokli Apr 10, 2018

Member

@pohly yes, sounds good, thanks :-)

Member

flokli commented Apr 10, 2018

@pohly yes, sounds good, thanks :-)

pohly added a commit to pohly/afew that referenced this issue Apr 11, 2018

documentation: installation and usage in docs/
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/#23.

@pohly pohly referenced this issue Apr 11, 2018

Merged

Update README.rst #191

@flokli flokli closed this in #191 Apr 11, 2018

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment