From mboxrd@z Thu Jan 1 00:00:00 1970 From: L p R n d n Subject: Re: Communication and Design at Guix Date: Mon, 14 Jan 2019 16:02:46 +0100 Message-ID: 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]:48891) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gj2pD-0001MQ-Ny for guix-devel@gnu.org; Mon, 14 Jan 2019 09:02:49 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gj2p7-0007EY-DI for guix-devel@gnu.org; Mon, 14 Jan 2019 09:02:47 -0500 Received: from mout01.posteo.de ([185.67.36.141]:47699) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1gj2p7-0007E1-4B for guix-devel@gnu.org; Mon, 14 Jan 2019 09:02:41 -0500 Received: from submission (posteo.de [89.146.220.130]) by mout01.posteo.de (Postfix) with ESMTPS id 049E7160061 for ; Mon, 14 Jan 2019 15:02:38 +0100 (CET) Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 43dZt333Pwz6tmP for ; Mon, 14 Jan 2019 15:02:35 +0100 (CET) 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: guix-devel@gnu.org HeLlO, Ludovic Court=C3=A8s writes: > Hi! > > Ricardo Wurmus skribis: > >> L p R n d n writes: >> >>>>> What about guix.info? We can do whatever we want there I suppose and = just link >>>>> to it from the gnu site. >>>> >>>> Well in general we can always do whatever we want. :-) I do think >>>> there=E2=80=99s value in presenting GNU manuals in a consistent way, t= hough, >>>> especially since Guix=E2=80=99 manual has cross-references to many oth= er >>>> manuals. >>> >>> That would be nice though. Even if consistency is enjoyable, I think >>> the benefits of a nicely shaped and organised documentation easily beat >>> what we could get from being consistent with non-Guix manuals. IMHO >>> GNU manuals are ok when you know what you're searching for, I find them >>> unreadable. + I think they're intimidating for newcomers. :/ > > I think it=E2=80=99s hard to generalize. What I do like about some GNU m= anuals > 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 goo= d.=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? > 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 shor= t-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. >> It=E2=80=99s fine to deviate from the consistent style. We do that alre= ady for >> the style sheet that=E2=80=99s used for our HTML documentation. Compare= this: >> >> https://www.gnu.org/software/sharutils/manual/html_node/index.html >> >> with this: >> >> https://www.gnu.org/software/guix/manual/en/html_node/index.html >> >> It=E2=80=99s fine to change our style sheet, but let=E2=80=99s stay with= Texinfo. > > Note that our manual uses https://gnu.org/software/gnulib/manual.css, > which is the standard CSS produced by Gnulib=E2=80=99s gendocs.sh, and th= is CSS > is used by many (most?) manuals at gnu.org, not just Guix. > > My suggestion was to improve this CSS, if L p R n d n is willing to make > the extra social effort to get changes accepted. If that doesn=E2=80=99t= work, > we can depart from that. > Thanks, > Ludo=E2=80=99. > Have a nice day, Lprndn