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: Sun, 13 Jan 2019 22:45:45 +0100 Message-ID: <87k1j81bau.fsf@gnu.org> References: <87k1jfuk26.fsf@gnu.org> <705CB66B-E8D5-4119-9F70-D429E1B174B2@pretty.Easy.privacy> <877efd1p56.fsf@gnu.org> <87r2dk4m4g.fsf@elephly.net> 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]:58272) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ginZs-0003oC-L1 for guix-devel@gnu.org; Sun, 13 Jan 2019 16:45:57 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ginZq-0003DB-Bs for guix-devel@gnu.org; Sun, 13 Jan 2019 16:45:56 -0500 Received: from hera.aquilenet.fr ([185.233.100.1]:58966) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1ginZo-00038r-C2 for guix-devel@gnu.org; Sun, 13 Jan 2019 16:45:54 -0500 In-Reply-To: <87r2dk4m4g.fsf@elephly.net> (Ricardo Wurmus's message of "Thu, 10 Jan 2019 15:34:39 +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: Ricardo Wurmus Cc: guix-devel@gnu.org, L p R n d n 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 j= ust 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, th= ough, >>> especially since Guix=E2=80=99 manual has cross-references to many other >>> 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 man= uals is that they=E2=80=99re well written and well structured; they can serve bo= th 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. 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 short-= term-ish, but I like the idea of working to help users understand what they=E2=80=99re do= ing, 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. > It=E2=80=99s fine to deviate from the consistent style. We do that alrea= dy 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 this= 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 w= ork, we can depart from that. Thanks, Ludo=E2=80=99.