Re: Proposed new introductory section to the Gnus manual

[Eric Abrahamsen <eric@ericabrahamsen.net>]

dick <dick.r.chiang@gmail.com> writes:

> "Lipstick on a pig" comes to mind when I think of patching documentation.
> If a system is sufficiently baroque that it's difficult to write concise
> documentation, then the battle was already lost (the shining counterpoint is
> K&R in which Kernighan famously writes "C is not a big language and ... is not
> well served by a big book").
>
> Certainly Gnus's intro documentation is (much) longer than it needs to be.
> Coders who also write documentation have an overriding tendency to explicate
> all that they know rather than condense to what the user cares to know
> (which is "how can i get on with my life?").

Yeah, I think that's where Gnus' manual is right now.

> I believe Gnus can be made less user-hostile so that lengthy and "jocular"
> documentation is unnecessary -- most Gmail and Thunderbird users never have to
> read consult docs.  I've been working steadily to write a "spacemacs for Gnus"
> (even though I dislike spacemacs).

Well hopefully we can simplify the code and improve the docs, and they
can meet somewhere in the middle.

What does "spacemacs for Gnus" mean?

Bob Newell <bobnewell@bobnewell.net> writes:

> Adam Sjøgren <asjo@koldfront.dk> writes:
>
>> It is indeed daunting to get started. (...)
>
>> I agree it would be good to have a more friendly/hand-holdey
>> introduction right there, in the manual.
>
> Today, over 10 years into Gnus, it's become something I couldn't
> possibly live without. But I do remember the initial suffering, back in
> whatever year it was, transitioning from ViewMail to Gnus on the advice
> of a colleague (who claimed it was 'easy').
>
> There are a couple of good tutorials on the internet. The one that says
> it features the 'essential 5%' (or thereabouts) is one I wish I had had
> when starting out. But information is still scattered in many places,
> and some of it is misleading.
>
> A layered 'official' manual would be a good thing. Start with the
> concept, then the 5%, then build up into the more complex stuff.

I will look for the one with the "essential 5%" and see if I can steal
from it, thanks for the tip!

While I think it will be fine to paste my "Gnus in 20 minutes" intro
into the front of the manual, eventually it would better to separate out
the rest of the manual into a "user guide" and "reference manual".

> Still, 'how low can you go' has its limits. Gnus, like tensor calculus
> or analysis of Old French texts, is not for everyone, and we don't want
> it to be. This is not an elitist statement nor is it a call to keep it
> obscure. It's just a recognition of the fact that a super-powerful and
> super-flexible tool that can be made to do almost anything comes at a
> price. That price is learning how to use it and being willing to feel
> the pain of mental exertion (and exasperation at times) along the
> way. We should strive to reduce the exasperation but the exertion, I
> think, will always remain.

Yeah, I think this is right. Including Adam's note about the
unfamiliarity of elisp itself -- while we can make the first steps
easier, users are eventually going to need to do their homework.

I've done another version of the intro based on everyone's feedback, but
when I've got an actual internet connection I'm going to look up the
guide you mentioned and see if I can steal from it.

Eric