Re: Communication and Design at Guix

["Ludovic Courtès" <ludo@gnu.org>]

Hi,

L  p R n  d n    <guix@lprndn.info> skribis:

[...]

>> I think it’s hard to generalize.  What I do like about some GNU manuals
>> is that they’re 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 good. 
> 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’ve seen on gnu.org don’t even have a CSS), and a
menu and visual hints would certainly help too.

>> I understand it’s a very different approach from what people do
>> nowadays, which is often more “quick-start” but also short-term-ish, but
>> I like the idea of working to help users understand what they’re doing,
>> as opposed to just throwing at them the minimum they need to know to get
>> things done.  It’s 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. 
>
> 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. 
> Probably not in the manual but in a separate part of documentation.
> (how we separate them is another question). 
> That kind of document can make the difference for a newcomer.

Maybe you’re right and that’s what I liked about Pierre’s tutorial.  The
manual also has a “Defining Packages” 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’.