Re: Regarding spam.el

[Jonas Steverud <tvrud@bredband.net>]

Ted Zlatanov <tzz@lifelogs.com> writes:


(I only saw your mails recently due to an accident with
gnus-split-with-parent,  which is ridiculous since I was keeping an eye
out for them. :-/)

> On Tue, 09 Mar 2004, tvrud@bredband.net wrote:
>
>> 1. Is gnus-group-*-exit-processor-bogofilter obsolete? If so, it
>>    should be better marked as such in the info file. Same for all
>>    similar obsolete variables.
>
> Those variables are obsolete, but I'm keeping them until the next
> major release of Gnus.  The ({spam|ham} spam-use-BACKEND) format will
> replace the processor variables.  How should these deprecations be
> marked, in bulk (a single note) or individually?  I'll add them.

Individually IMHO.

Maybe something like this:

 - Variabel: gnus-group-spam-exit-processor-bogofilter (obsolete)

That way the user can skip the entire description and not find out
afterwards that it is obsolete. When I read it I know some variables
are obsolete and since I don't remember which I have to scan downward
each time I reach a variable to see if it is obsolete or not. It
definitely reduces the reading speed and adds a bit of confusion.

> I think that's explained clearly.  Feel free to suggest alternate wording.

See below.

>> What can they be set to?
>
> That's what the customize interface is for.  I don't want to explain
> every possible option - as you noticed, the information is very dense
> already.

Yes, and I think that is part of the problem - the information is very
dense. Writing documentation is not a contest in writing with as few
words as possible (not in any way claiming that you participate in
such a contest ;-) ), it is actually a contest in writing more words
then you think is necessary. There are extremes off course as any
university student can testify about, some authors are payed by the
page number. I've written quite a few documents in my time (does ISO
9000 and ISO 9001 ring a bell?) and in my experience, there
are numerous occasions when one think that "this is enough" - and that
is exactly not the case. One should always write ten per cent more
then one think is necessary.

What the documentation really needs is more words.

E.g. the sequence of events needs a list of the stages at the beginning,
i.e. 1) Stage A, 2) Stage B etc., and then each stage is describes in
a sub topic of its own if they become lengthy or at least under a
headline. OTOH the nodes in a info file are very short so it shouldn't
be a problem to have a node for each stage.


>> The reader only gets confused. Either a reference to a info node or
>> explaination text is needed.  The paragraph after explains it but
>> not very clear. An example woul be very nice.
>
> My setup in "Spam ELisp Package Configuration Examples" uses
> spam-autodetect. 

Yes, and that is very good! Maybe include a pointer to that section?

In general, the examples in "this is my setup" are usually quite
complex (which is good!) but to understand the concept they need to be
very simple.

I.e. include a very simple example where you describe the
variable/concept: "To do Foo, set the bar variable to X, i.e. add the
following line of code to the group parameter: (BAR . X)" where Foo is
a very simple thing. Have a look at the examples for e.g. splitting
mail, they are usually very simple but very descriptive.

Sorry, but I have no specific suggestions.


>> 3. There are several group parameters and variables mentioned in the
>>    info file and it is not always obvious which is which. A separate
>>    page/node or at the end of one of the nodes with a list of all
>>    variables and the corresponding parameters with examples would be
>>    a good idea.
>
> I'm not sure at all what you mean here.

What I tried to say is that in some places a number of parameters and
variables is introduced ("blah X blah Y blah Z blah") but it is not
clear if X is a parameter or a variable. If X is a parameter, is then
Y and Z it as well or can it be so that X and Z are parameters and Y
is a variable? If X is a parameter, what is then the corresponding
global variable (because it is mentioned that for each parameter,
there is a variable, but no hint of naming scheme)?

E.g. from the sequence of events:
------
   If a spam is found in any group (this can be changed to only non-spam
groups with `spam-move-spam-nonspam-groups-only'), it is processed by
the active `spam-processors' (*note Spam ELisp Package Global
Variables::) when the group is exited.  Furthermore, the spam is moved
------

Is spam-move-spam-nonspam-groups-only a parameter or a variable? I
have to look at the example to
know. spam-move-spam-nonspam-groups-only is only mentioned twice,
above and in the example. I will not be able to read the docs with C-h v 
unless I load the spam.el package. Which I probably won't do before I
understood that I have to do that and how I will be able to do it. I
will not load it before I've understood what will happen when I do. If
you catch my drift (or however the expression goes).

> Have you tried the customize interface [...]

Nope, I prefer the old fashioned way of typing Lisp one-liners on a
neural interface... ;-)

Besides, my aim with this is to "debug" the manual, to try to find
the parts which confuses me. Using the customize interface is not
exactly cheating, but isn't exactly right either.

(And I only used the customize interface once before for JDEE and I
can't say that I know how to handle it.)


> A lot of readers jump to the section of interest.

Yes, I am like that myself. But when one reads something for the first
time it is a good idea to start on the first page and read then in
sequence. You have to know that something is of interest before you
can jump there, so to speak. ;-)

> Reread the explanations of gnus-{spam,ham}-process-destinations and
> see if they make more sense after my fixes.

Which are in CVS I expect. I've decided that I will use the released
versions of No Gnus, so I will see the new text when 0.02 is released.

>>    d. In the example section gives the following example:
>>       ((spam-process-destination .
>>       "nnimap+mail.lifelogs.com:train")) When did a string become a
>>       (REGEXP PROCESSOR) or (REGEXP GROUP)?  Same goes for
>>       (ham-process-destination "nnimap+mail.lifelogs.com:mail"
>>       "nnimap+mail.lifelogs.com:trainham")
>
> That's the group/topic parameter, whereas the paragraphs above were
> talking about the gnus-{spam,ham}-process-destinations variables.

See my comment above about distinguishing between parameters and variables.

> There is one reason why I'm not good at documenting spam.el: I know it
> too well.  Where someone else might say, "wait, why is this variable
> mentioned here" or "what does that parameter mean?" I can miss those
> spots.  So it's not intentional that the documentation is confusing,
> and I want to make it better.

That is way I send these emails. I want to help with that, to point
out the places that needs to be fleshed out. I might not be able with
the text to write yet since I need to understand more of it before,
but I hope my questions and points helps you understand how others
read the documentation.

(I better add a disclaimer at once: If I ever sounds like I'm ranting,
 that is not my intention. :-) )

Enjoy.

/Jonas 
-- 
(        http://hem.bredband.net/steverud/        !     Wei Wu Wei     )
(        Meaning of U2 Lyrics, Roleplaying        !  To Do Without Do  )