Re: Communication and Design at Guix

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

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.

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.

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