You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@spamassassin.apache.org by bu...@bugzilla.spamassassin.org on 2006/11/29 19:09:13 UTC
[Bug 5213] New: can't find documentation on individual tests
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
Summary: can't find documentation on individual tests
Product: Spamassassin
Version: unspecified
Platform: All
OS/Version: All
Status: NEW
Severity: normal
Priority: P5
Component: Documentation
AssignedTo: dev@spamassassin.apache.org
ReportedBy: per@bothner.com
I have not been able to find on the website any page that documents each test
properly. This page http://spamassassin.apache.org/tests_3_1_x.html has a
*list* of the tests with a *very* terse description, but that really isn't
sufficient. In addition, for each test there needs to be a link to further
description: a short paragraph explaining what is tested, why it is or can be
useful in detecting spam, and downsides (likelyhood of false positives as well
as network and computational costs).
If there is such a description, it is awfully well hidden. There should be
links in the above-mentioned page, plus an entry in the faq. Otherwise
spamassassin becomes just a black box.
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From shiva@sewingwitch.com 2006-11-29 15:50 -------
See also bug 4771.
http://wiki.apache.org/spamassassin/RulesList
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From craigsa@2cah.com 2006-11-29 10:56 -------
The best source of documentation for the rules are the .cf files themselves.
man or perldoc spamassassin
Will lead you to where the configuration/rules' files are stored.
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From craigsa@2cah.com 2006-11-29 11:55 -------
(In reply to comment #4)
> Hipefully you'll agree that's not a very good situation. "Read the source" is
> not exactly a good answer for any documentation, and even less so for standard
> user-settable configuration options.
Maybe that is a given, but the point of contention is 'Is spamassassin well
documented?' Yes, it is, via perldoc.
Spamassassin is an open source project, which is open to user contributions.
Those contributions are not limited to the inner workings (read: source code),
contributions to the documentation and wiki pages are more than gratefully accepted.
If we aren't satisfied with the current state of affairs we have 2 options: 1)
Complain about it, 2) get involved and be a part of the solution. Which a person
decides to do is their choice but the latter of the two will definitely make
more friends and increase the karma of the project as a whole.
(In reply to comment #4)
> (In reply to comment #2)
> > The best source of documentation for the rules are the .cf files themselves.
>
> Hipefully you'll agree that's not a very good situation. "Read the source" is
> not exactly a good answer for any documentation, and even less so for standard
> user-settable configuration options.
>
>
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From per@bothner.com 2006-11-29 11:08 -------
(In reply to comment #2)
> The best source of documentation for the rules are the .cf files themselves.
Hipefully you'll agree that's not a very good situation. "Read the source" is
not exactly a good answer for any documentation, and even less so for standard
user-settable configuration options.
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From per@bothner.com 2006-11-29 16:30 -------
(In reply to comment #5)
> I think that this could be useful, but I think it would require a large amount
> of effort and time.
True, but one could start with a template and a policy. Apparently somebody
created a template already (bug 4771), using what seems a reasonable URL pattern:
http://wiki.apache.org/spamassassin/Rules/<RULE_NAME>
So what needs to happen is
(1) get consensus that rule-specific documentation should use that URL.
(2) get consensus that as a *goal* all rules should have such documentation.
This does not means assinging priorities. (However, you might consider a policy
that all now rules or majorly re-written rules need documentation before they
can be part of the standard rule-base.)
(3) a couple of sample rules should be documented;
(4) Each documented test should have a link in tests_3_1_x.html.
> As we are an open-source project, we welcome contributions
> from others. Perhaps you would like to write this documentation?
Sorry, I have neither the experise and time. I'm very busy with my own
open-source projects. I realize I have no claims to anyone's time; this is just
a wishlist item - but I think it would be very helpful.
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From duncf@debian.org 2006-11-29 11:41 -------
Per, you are correct in that SpamAssassin currently does not have this
documentation.
I think that this could be useful, but I think it would require a large amount
of effort and time. As we are an open-source project, we welcome contributions
from others. Perhaps you would like to write this documentation?
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
felicity@apache.org changed:
What |Removed |Added
----------------------------------------------------------------------------
Status|NEW |RESOLVED
Resolution| |DUPLICATE
------- Additional Comments From felicity@apache.org 2006-11-29 16:32 -------
*** This bug has been marked as a duplicate of 4771 ***
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From lwilton@earthlink.net 2006-11-29 10:21 -------
What's wrong with a black box if it does what it says it is supposed to do?
Do cars come with a physics textbook describing the metalurgy of every part in
the car and the physics of internal combustion engines?
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.
[Bug 5213] can't find documentation on individual tests
Posted by bu...@bugzilla.spamassassin.org.
http://issues.apache.org/SpamAssassin/show_bug.cgi?id=5213
------- Additional Comments From per@bothner.com 2006-11-29 11:05 -------
(In reply to comment #1)
> What's wrong with a black box if it does what it says it is supposed to do?
You're joking, right? Get back to me when Apamassassin correctly stops all and
only spam in its default installation without needing any tweaking.
Cars do come with instruction manuals, btw.
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.