From mboxrd@z Thu Jan 1 00:00:00 1970 X-Msuck: nntp://news.gmane.io/gmane.emacs.gnus.general/88755 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Eric Abrahamsen Newsgroups: gmane.emacs.gnus.general Subject: Re: Proposed new introductory section to the Gnus manual Date: Mon, 09 Sep 2019 16:13:06 +0800 Message-ID: <87d0g9q44t.fsf@ericabrahamsen.net> References: <87o90mm4x2.fsf@ericabrahamsen.net> <87blwmuh6j.fsf@dick.i-did-not-set--mail-host-address--so-tickle-me> <87mug6klq3.fsf@ericabrahamsen.net> <87mug5bpuh.fsf@ucl.ac.uk> <87y2zojwbz.fsf@ericabrahamsen.net> <871rxggj9l.fsf@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="123777"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.0.50 (gnu/linux) To: ding@gnus.org Original-X-From: ding-owner+M36959@lists.math.uh.edu Mon Sep 09 10:18:44 2019 Return-path: Envelope-to: ding-account@gmane.org Original-Received: from lists1.math.uh.edu ([129.7.128.208]) by blaine.gmane.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1i7Esj-000Vys-UY for ding-account@gmane.org; Mon, 09 Sep 2019 10:18:42 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.math.uh.edu) by lists1.math.uh.edu with smtp (Exim 4.92) (envelope-from ) id 1i7Esf-0006FC-Fb; Mon, 09 Sep 2019 03:18:37 -0500 Original-Received: from mx1.math.uh.edu ([129.7.128.32]) by lists1.math.uh.edu with esmtps (TLSv1.3:TLS_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1i7Esc-0006CZ-Gf for ding@lists.math.uh.edu; Mon, 09 Sep 2019 03:18:34 -0500 Original-Received: from quimby.gnus.org ([80.91.231.51]) by mx1.math.uh.edu with esmtps (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256) (Exim 4.92) (envelope-from ) id 1i7Esb-0000VP-2s for ding@lists.math.uh.edu; Mon, 09 Sep 2019 03:18:34 -0500 Original-Received: from 195-159-176-226.customer.powertech.no ([195.159.176.226] helo=blaine.gmane.org) by quimby.gnus.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1i7EsX-0002fy-KX for ding@gnus.org; Mon, 09 Sep 2019 10:18:31 +0200 Original-Received: from list by blaine.gmane.org with local (Exim 4.89) (envelope-from ) id 1i7EsW-000Vlp-S9 for ding@gnus.org; Mon, 09 Sep 2019 10:18:28 +0200 X-Injected-Via-Gmane: http://gmane.org/ Cancel-Lock: sha1:NQGT3HkVSnTDb1j4r9vajdxKWZs= List-ID: Precedence: bulk Xref: news.gmane.org gmane.emacs.gnus.general:88755 Archived-At: dick 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 writes: > Adam Sjøgren 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