GNU bug report logs - #37078
27.0.50; Proposal: new introductory section to the Gnus manual

Previous Next

Full log

View this message in rfc822 format

From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 37078 <at> debbugs.gnu.org
Subject: bug#37078: 27.0.50; Proposal: new introductory section to the Gnus manual
Date: Fri, 24 Jul 2020 11:49:19 -0700

[Message part 1 (text/plain, inline)]

On 07/23/20 20:43 PM, Eli Zaretskii wrote:
>> From: Eric Abrahamsen <eric <at> ericabrahamsen.net>
>> Cc: larsi <at> gnus.org,  37078 <at> debbugs.gnu.org
>> Date: Thu, 23 Jul 2020 09:59:14 -0700
>> 
>> > Most of this section should be under the "Composing Messages" chapter,
>> > IMO.
>> 
>> We had a bit of discussion on gnus.general about this. My feeling is
>> that Gnus has a "how do I exit vim" problem: people start it up, can't
>> figure out why they can't see their email, bang on the keyboard a bit,
>> then rage quit. I figured it would only take a tiny bit of information
>> to fix that: the fact that Gnus hides read groups/articles by default,
>> and the ~eight commands necessary to do basic maneuvering. Other people
>> felt it was weird to combine conceptual overviews with a handful of
>> keybindings, and I can understand that. But I really meant this section
>> to be "get to usability in 20 minutes".
>> 
>> But you're right that the three fetching/reading/sending sections
>> shouldn't be there (the fact that I was getting chapter name collisions
>> should have been a clue). I'll check the existing sections and see if
>> they can be made to provide an easier on-ramp, then just link to those.
>
> The introduction you wrote can mention the main points briefly, and
> then have a cross-reference to where the commands are described in
> full.  That way, both those who don't know "how to exit vim" will find
> what they need (and can follow the cross-reference to read the rest),
> and those who read the relevant chapter will have this information
> spelled out.

Okay, here's another stab at it. Since the sections have been slimmed
down I've just turned them into headings, which I think aids digestion
and removes the heading collision problem.

I feel like adding cross references to the first paragraph of "The
Basics of Servers, Groups, and Articles" has made it even harder to
parse, and am inclined to turn that into an unordered list of three
terms.

Otherwise, WDYT?

Eric

[gnus-intro.diff (text/x-patch, attachment)]

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.