From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?utf-8?Q?Ludovic_Court=C3=A8s?= Subject: Re: Communication and Design at Guix Date: Tue, 15 Jan 2019 23:28:26 +0100 Message-ID: <87tvi9wo6t.fsf@gnu.org> References: <87k1jfuk26.fsf@gnu.org> <705CB66B-E8D5-4119-9F70-D429E1B174B2@pretty.Easy.privacy> <877efd1p56.fsf@gnu.org> <87r2dk4m4g.fsf@elephly.net> <87k1j81bau.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Return-path: Received: from eggs.gnu.org ([209.51.188.92]:43715) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gjXCE-0007ss-RO for guix-devel@gnu.org; Tue, 15 Jan 2019 17:28:35 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gjXCA-00050q-Og for guix-devel@gnu.org; Tue, 15 Jan 2019 17:28:32 -0500 Received: from hera.aquilenet.fr ([185.233.100.1]:49342) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1gjXC9-0004wY-Uw for guix-devel@gnu.org; Tue, 15 Jan 2019 17:28:30 -0500 In-Reply-To: (L. p. R. n. d. n.'s message of "Mon, 14 Jan 2019 16:02:46 +0100") List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: L p R n d n Cc: guix-devel@gnu.org Hi, L p R n d n skribis: [...] >> I think it=E2=80=99s hard to generalize. What I do like about some GNU = manuals >> is that they=E2=80=99re well written and well structured; they can serve= both as >> a reference and as a way to get started. Examples of these include the >> libc and the Emacs manuals. These are really book-quality, and are >> actually published as such. > > Just to be clear, I was not talking about the content of the manuals. I'm > in no position to judge their quality. And as you said, some are really g= ood.=20 > I'm giving my opinion about the global layout, shape, css used in most > of their manuals. I find them difficult to read (probably not true if > you're used to them) because of things like contrast, lenght of lines > etc. Without modifying the content, visual hints and helpers can really > enhance the reading experience. Things like a left menu (as proposed by > swedebugia) can be, IMHO, the difference between a read manual and an > unread manual. > WDYT? Oh I agree with you: a better CSS would improve things (note that the ugliest manuals you=E2=80=99ve seen on gnu.org don=E2=80=99t even have a CS= S), and a menu and visual hints would certainly help too. >> I understand it=E2=80=99s a very different approach from what people do >> nowadays, which is often more =E2=80=9Cquick-start=E2=80=9D but also sho= rt-term-ish, but >> I like the idea of working to help users understand what they=E2=80=99re= doing, >> as opposed to just throwing at them the minimum they need to know to get >> things done. It=E2=80=99s about emancipating users, after all. > > I totally agree with you here. The goal must be to empower the user. > But I also think manuals like we have and quickstart/cookbooks are not > opposed but complementary. The latter are here to help people find their > way without being overwhelmed by the quantity of information of a > manual. The former really shines once a user has been introduced to the > subject.=20 > > For example, I think the packaging tutorial written by Pierre Neidhardt > could really find its place in the documention (if the author agrees > obviously). It's a nice *bridge* from guix user to guix hacker.=20 > Probably not in the manual but in a separate part of documentation. > (how we separate them is another question).=20 > That kind of document can make the difference for a newcomer. Maybe you=E2=80=99re right and that=E2=80=99s what I liked about Pierre=E2= =80=99s tutorial. The manual also has a =E2=80=9CDefining Packages=E2=80=9D section with similar = goals, and I like the idea of having introductory material like this directly in the manual, but sometimes a separate and informal document can help too. Thanks, Ludo=E2=80=99.