Re: Communication and Design at Guix

[L p R n d n <guix@lprndn.info>]

HeLlO,

Ludovic Courtès <ludo@gnu.org> writes:

> Hi!
>
> Ricardo Wurmus <rekado@elephly.net> skribis:
>
>> L p R n d n <guix@lprndn.info> 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’s value in presenting GNU manuals in a consistent way, though,
>>>> especially since Guix’ 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’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?

> 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.

>> It’s fine to deviate from the consistent style.  We do that already for
>> the style sheet that’s 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’s fine to change our style sheet, but let’s stay with Texinfo.
>
> Note that our manual uses https://gnu.org/software/gnulib/manual.css,
> which is the standard CSS produced by Gnulib’s 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’t work,
> we can depart from that.
> Thanks,
> Ludo’.
>
Have a nice day,

Lprndn