Bug 4679 - Bayes is undocumented in README, USAGE, INSTALL and UPGRADE
Summary: Bayes is undocumented in README, USAGE, INSTALL and UPGRADE
Status: NEW
Alias: None
Product: Spamassassin
Classification: Unclassified
Component: Documentation (show other bugs)
Version: SVN Trunk (Latest Devel Version)
Hardware: Other other
: P5 normal
Target Milestone: Undefined
Assignee: SpamAssassin Developer Mailing List
URL: http://bugs.debian.org/cgi-bin/bugrep...
Whiteboard:
Keywords:
Depends on:
Blocks:
 
Reported: 2005-11-09 22:15 UTC by spamassassin
Modified: 2005-11-22 11:29 UTC (History)
0 users



Attachment Type Modified Status Actions Submitter/CLA Status

Note You need to log in before you can comment on or make changes to this bug.
Description spamassassin 2005-11-09 22:15:45 UTC
There is no explanation of what Bayes is or how it works in README (or any of
the other text files). There is a very small reference to perldoc sa-learn, but
it could easily be missed.

We really need to improve our documentation

Specifically, where is the "200 ham, 200 spam" requirement documented, for example.
Comment 1 Justin Mason 2005-11-10 00:30:01 UTC
I think we should just slim down the distributed file-based docs (README,
UPGRADE, INSTALL etc.) to the bare minimum, go into (painful) detail on the
wiki, and do everything possible to ensure that installers read that instead.

As a collaborative documentation platform, the wiki has already proved much more
effective than our SVN codebase.

(However, reference docs should still be maintained as POD on the modules and
scripts.  I'm just talking about the task-based documentation parts.)
Comment 2 Duncan Findlay 2005-11-11 04:12:35 UTC
Describing what a major part of the functionality does is hardly task-based. I
really would like to see a useful set of documents distributed with the source.

Having said that, I definitely dont have the time to construct such a set, so I
expect this bug to remain open for a while. ;-)
Comment 3 Justin Mason 2005-11-11 04:32:39 UTC
I'll repeat:

'As a collaborative documentation platform, the wiki has already proved much more
effective than our SVN codebase.'

that's the key point IMO.
Comment 4 Tom Schulz 2005-11-22 15:21:35 UTC
The following email did not make it into the bug as a comment, so here it is.

> 'As a collaborative documentation platform, the wiki has already proved
> much more
> effective than our SVN codebase.'

So why not write a routine to scrape the Wiki on the day of release and
stick the pages into files in the release tree?

        Loren
Comment 5 John Gardiner Myers 2005-11-22 17:53:16 UTC
(In reply to comment #4)
> So why not write a routine to scrape the Wiki on the day of release and
> stick the pages into files in the release tree?

That removes a key advantage of the Wiki: that it continues to be updated after
the release.
Comment 6 Justin Mason 2005-11-22 20:29:12 UTC
'So why not write a routine to scrape the Wiki on the day of release and
stick the pages into files in the release tree?'

fwiw, we are probably going to have to do something like this anyway, since the
README files etc. have already found their way into the wiki:

http://wiki.apache.org/spamassassin/BetterDocumentation/ReadmeTxt
http://wiki.apache.org/spamassassin/BetterDocumentation