Re: Proposed new introductory section to the Gnus manual

["Adam Sjøgren" <asjo@koldfront.dk>]

Eric writes:

> Let me know if you have any comments/questions/suggestions!

Nitpicks and comments follow.

> 			     ━━━━━━━━━━━━━
> 			      DON’T PANIC
> 			     ━━━━━━━━━━━━━

It's cute with a Douglas Adams reference, but I think a headline that is
more descriptive of the contents is warranted.

> Welcome, gentle user, to the Gnus newsreader and email client! Gnus is
> unlike most clients, in part because of its gross configurability, and

I agree with (the other) Eric that "gross" sounds a little too.. icky?

> While Gnus is now a fully-featured email client, it began life as a
> newsreader, and its DNA is still newsreader DNA.

I think I understand where you are going with this, but Gnus is still a
newsreader, right? This sentence sounds like it isn't anymore.

> 3. Gnus will only show you groups with unread or ticked articles;

Is "ticked" articles a Gnusism? Maybe "marked" or "flagged" would be
more accessible to a newcomer?

Come to think of it, will the average email user who hasn't heard of
usenet know that "article" for mail is synonymous with "email"? A little
later you use the term "message", which might be less confusing up here
as well?

> If this seems draconian, think of it as Enforced Inbox Zero.

"Enforced" sounds so negative. Automatic Inbox Zero? "Now, with more AIZ!"

> This is the way Gnus works by default. It is possible to make it work
> more like an email client (always showing read groups and read
> messages), but that will take some effort on the part of the user, and
> Gnus won’t ever really like it.

Does Gnus have an opinion? It's more like it is unnatural or counter to
the design, right?

(I said I would nitpick...)

>   When sending messages, too, Gnus makes a distinction between news-like
>   and mail-like behavior. News servers handle mail delivery themselves,

Perhaps "message delivery"?

>   Mail message composition starts with “m” in the *Group* buffer, or “r”
>   if you’re replying to an existing message.

Won't most users expect to use R or F, rather than r?

                                 o o o

I'm not really sure where you're aiming with this. It's too vague to be
a tutorial, it's too limited to be a manual. An email-biased
introduction? Perhaps use a headline to set the tone/ambition.

It is hard to write a tutorial without getting bogged down in details
that won't fit every reader, I know - even from experience.

Maybe it's been too long since I've read the manual. (And no, I won't go
read any of the vim-tutorials you referred to ;-))

I think I sound more negative than I wanted to, here. It makes sense to
me, to have a more gentle introduction/overview in the beginning of the
manual and I think you've got a good start.

Documentation is hard, let's go code.


  Best regards,

    Adam

-- 
 "Lanois can get passionate about what he feels to be         Adam Sjøgren
  true," Dylan said. "He's not above smashing guitars.   asjo@koldfront.dk
  I never cared about that unless it was one of mine."