Communication and Design at Guix

Communication and Design at Guix

[L p R n d n]

Hello Guix,

After taking some time learning Guix and trying to get some new packages
in, I wanted get involved in a slightly different way. I'm not good at
programming and I think my time might be better used participating in
tasks a little more inline with my skills.
The thing is that I find "design" and "communication" (take it in a very broad
way) often a little more complex and delicate to tackle in a group
project. This is why I'm introducing the idea with this mail.

I think the Guix project could benefit a lot from dealing with the
"rest of the world" and how it wants to show itself. It might even help
clarify some technical decisions if needed. Bonus is that next release
will probably be 1.0 and that it means Guix will get extra attention.

I have a few things I would like to talk about but, as I don't want to
force aniything on anyone, I wanted to first have your thoughts about this and
eventually what you guix people think would be nice to tackle on. (I
think I saw something about a wiki somewhere for example etc.)

By the way, I wanted to start working on the documentation. 
IMHO, it might benefit from a little graphical enhancement for
newcomers. The thing is that it's currently hosted on
gnu.org so it's probably not possible to modify the design. So I wanted
to ask, first, if that's something that would be welcome? What could be
the possibilities? And what would be the technical limitations?

Thank you for your time,
Have a nice day,

Lprndn

Re: Communication and Design at Guix

[Ludovic Courtès]

Hello,

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

> After taking some time learning Guix and trying to get some new packages
> in, I wanted get involved in a slightly different way. I'm not good at
> programming and I think my time might be better used participating in
> tasks a little more inline with my skills.
> The thing is that I find "design" and "communication" (take it in a very broad
> way) often a little more complex and delicate to tackle in a group
> project. This is why I'm introducing the idea with this mail.

This is one of the non-programming activities where Guix needs help so
I’m glad you’re offering to contribute!

> I think the Guix project could benefit a lot from dealing with the
> "rest of the world" and how it wants to show itself. It might even help
> clarify some technical decisions if needed. Bonus is that next release
> will probably be 1.0 and that it means Guix will get extra attention.
>
> I have a few things I would like to talk about but, as I don't want to
> force aniything on anyone, I wanted to first have your thoughts about this and
> eventually what you guix people think would be nice to tackle on. (I
> think I saw something about a wiki somewhere for example etc.)

I’m not sure we need a wiki.  :-)

A very concrete task that could be of interest to you is the “name
change” (a bit of a strong word) that we’d like to implement by 1.0.
I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
confuses things: people visit the web site, they see a “GuixSD” logo and
get confused because they were just looking for a package manager, not a
whole distro, or they think “GuixSD” is a storage device ;-), things
like that.

The idea is to bring everything under the “Guix” name.  Most of the
time, writing “Guix” is good enough—after all, one can run ‘guix system’
on a foreign distro, too.  When we really need to make the distinction,
for instance in the manual, we would write “Guix System” to designate
what we currently call “GuixSD”.

This has implications mostly on the web site and on the manual.  Ricardo
sketched web site modifications here:

  https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00300.html

It would probably have further implications on how we present
Guix/GuixSD.

WDYT?

> By the way, I wanted to start working on the documentation. 
> IMHO, it might benefit from a little graphical enhancement for
> newcomers. The thing is that it's currently hosted on
> gnu.org so it's probably not possible to modify the design. So I wanted
> to ask, first, if that's something that would be welcome? What could be
> the possibilities? And what would be the technical limitations?

The HTML pages at gnu.org/s/guix/manual are generated from Texinfo.  The
CSS there is shared with all the GNU manuals, which is nice for
consistency.  Ideally modifications of the CSS would be submitted to the
GNU webmaster or bug-gnulib@gnu.org (I forgot which one).  However, be
aware that you may encounter misplaced conservatism if you take that
route, so don’t lose your hair on it.

Thanks,
Ludo’.

Re: Communication and Design at Guix

[swedebugia]

[-- Attachment #1.1: Type: text/html, Size: 4927 bytes --]

[-- Attachment #1.2: Type: text/plain, Size: 4115 bytes --]

"Ludovic Courtès" <ludo@gnu.org> skrev: (8 januari 2019 18:37:53 CET)
>Hello,
>
>L  p R n  d n    <guix@lprndn.info> skribis:
>
>> After taking some time learning Guix and trying to get some new
>packages
>> in, I wanted get involved in a slightly different way. I'm not good
>at
>> programming and I think my time might be better used participating in
>> tasks a little more inline with my skills.
>> The thing is that I find "design" and "communication" (take it in a
>very broad
>> way) often a little more complex and delicate to tackle in a group
>> project. This is why I'm introducing the idea with this mail.
>
>This is one of the non-programming activities where Guix needs help so
>I’m glad you’re offering to contribute!
>
>> I think the Guix project could benefit a lot from dealing with the
>> "rest of the world" and how it wants to show itself. It might even
>help
>> clarify some technical decisions if needed. Bonus is that next
>release
>> will probably be 1.0 and that it means Guix will get extra attention.
>>
>> I have a few things I would like to talk about but, as I don't want
>to
>> force aniything on anyone, I wanted to first have your thoughts about
>this and
>> eventually what you guix people think would be nice to tackle on. (I
>> think I saw something about a wiki somewhere for example etc.)
>
>I’m not sure we need a wiki.  :-)
>
>A very concrete task that could be of interest to you is the “name
>change” (a bit of a strong word) that we’d like to implement by 1.0.
>I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
>confuses things: people visit the web site, they see a “GuixSD” logo
>and
>get confused because they were just looking for a package manager, not
>a
>whole distro, or they think “GuixSD” is a storage device ;-), things
>like that.
>
>The idea is to bring everything under the “Guix” name.  Most of the
>time, writing “Guix” is good enough—after all, one can run ‘guix
>system’
>on a foreign distro, too.  When we really need to make the distinction,
>for instance in the manual, we would write “Guix System” to designate
>what we currently call “GuixSD”.
>
>This has implications mostly on the web site and on the manual. 
>Ricardo
>sketched web site modifications here:
>
>  https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00300.html
>
>It would probably have further implications on how we present
>Guix/GuixSD.
>
>WDYT?
>
>> By the way, I wanted to start working on the documentation. 
>> IMHO, it might benefit from a little graphical enhancement for
>> newcomers. The thing is that it's currently hosted on
>> gnu.org so it's probably not possible to modify the design. So I
>wanted
>> to ask, first, if that's something that would be welcome? What could
>be
>> the possibilities? And what would be the technical limitations?
>
>The HTML pages at gnu.org/s/guix/manual are generated from Texinfo. 
>The
>CSS there is shared with all the GNU manuals, which is nice for
>consistency.  Ideally modifications of the CSS would be submitted to
>the
>GNU webmaster or bug-gnulib@gnu.org (I forgot which one).  However, be
>aware that you may encounter misplaced conservatism if you take that
>route, so don’t lose your hair on it.
>
>Thanks,
>Ludo’.

What about guix.info? We can do whatever we want there I suppose and just link to it from the gnu site.

Talking about CSS and the manual I would like to add patens highlighting.
The chicken documentation has this (on mouse over) and it is really nice to be able to see how complicated expressions are composed.

Also it would be really nice with a guix style guide apart from the manual and a script to go through the code and autodocument from all the docstrings.
(In the repl ,apropos can do a little something like this) I got this idea from php reading the code of dolibarr.
I'm mentioning this because it is important to know what procedures are where in our code for new contributors.
-- 
Sent from my p≡p for Android.

[-- Attachment #2: pEpkey.asc --]
[-- Type: application/pgp-keys, Size: 3825 bytes --]

Re: Communication and Design at Guix

[Ludovic Courtès]

Hi swedebugia,

swedebugia <swedebugia@riseup.net> skribis:

>>> By the way, I wanted to start working on the documentation. 
>>> IMHO, it might benefit from a little graphical enhancement for
>>> newcomers. The thing is that it's currently hosted on
>>> gnu.org so it's probably not possible to modify the design. So I
>>wanted
>>> to ask, first, if that's something that would be welcome? What could
>>be
>>> the possibilities? And what would be the technical limitations?
>>
>>The HTML pages at gnu.org/s/guix/manual are generated from Texinfo. 
>>The
>>CSS there is shared with all the GNU manuals, which is nice for
>>consistency.  Ideally modifications of the CSS would be submitted to
>>the
>>GNU webmaster or bug-gnulib@gnu.org (I forgot which one).  However, be
>>aware that you may encounter misplaced conservatism if you take that
>>route, so don’t lose your hair on it.

[...]

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

> Talking about CSS and the manual I would like to add patens highlighting.
> The chicken documentation has this (on mouse over) and it is really nice to be able to see how complicated expressions are composed.

Yes I’d love that too!  It should be doable for the “@lisp” Texinfo
bits.

Thanks,
Ludo’.

Re: Communication and Design at Guix

[L p R n d n]

Hello,

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

> Hi swedebugia,
>
> swedebugia <swedebugia@riseup.net> skribis:
>
>>>> By the way, I wanted to start working on the documentation. 
>>>> IMHO, it might benefit from a little graphical enhancement for
>>>> newcomers. The thing is that it's currently hosted on
>>>> gnu.org so it's probably not possible to modify the design. So I
>>>wanted
>>>> to ask, first, if that's something that would be welcome? What could
>>>be
>>>> the possibilities? And what would be the technical limitations?
>>>
>>>The HTML pages at gnu.org/s/guix/manual are generated from Texinfo. 
>>>The
>>>CSS there is shared with all the GNU manuals, which is nice for
>>>consistency.  Ideally modifications of the CSS would be submitted to
>>>the
>>>GNU webmaster or bug-gnulib@gnu.org (I forgot which one).  However, be
>>>aware that you may encounter misplaced conservatism if you take that
>>>route, so don’t lose your hair on it.
>
> [...]
>
>> 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. :/  


>> Talking about CSS and the manual I would like to add patens highlighting.
>> The chicken documentation has this (on mouse over) and it is really nice to be
>> able to see how complicated expressions are composed.
>
> Yes I’d love that too!  It should be doable for the “@lisp” Texinfo
> bits.

+1

> Thanks,
> Ludo’.

Thanks,

Lprndn

Re: Communication and Design at Guix

[swedebugia]

[-- Attachment #1: Type: text/plain, Size: 2041 bytes --]

L  p R n  d n <guix@lprndn.info> skrev: (10 januari 2019 13:09:48 CET)
>Hello,
>
>Ludovic Courtès <ludo@gnu.org> writes:
>
>> Hi swedebugia,
>>
>> swedebugia <swedebugia@riseup.net> skribis:
>>
>>>>> By the way, I wanted to start working on the documentation. 
>>>>> IMHO, it might benefit from a little graphical enhancement for
>>>>> newcomers. The thing is that it's currently hosted on
>>>>> gnu.org so it's probably not possible to modify the design. So I
>>>>wanted
>>>>> to ask, first, if that's something that would be welcome? What
>could
>>>>be
>>>>> the possibilities? And what would be the technical limitations?
>>>>
>>>>The HTML pages at gnu.org/s/guix/manual are generated from Texinfo. 
>>>>The
>>>>CSS there is shared with all the GNU manuals, which is nice for
>>>>consistency.  Ideally modifications of the CSS would be submitted to
>>>>the
>>>>GNU webmaster or bug-gnulib@gnu.org (I forgot which one).  However,
>be
>>>>aware that you may encounter misplaced conservatism if you take that
>>>>route, so don’t lose your hair on it.
>>
>> [...]
>>
>>> 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 agree with you to some degree. I like  the design of both the racket documentation and readthedocs. Especially the left menu gives a nice overview and searchability on page is also nice.

-- 
Sent from my p≡p for Android.

[-- Attachment #2: pEpkey.asc --]
[-- Type: application/pgp-keys, Size: 3825 bytes --]

Re: Communication and Design at Guix

[Ricardo Wurmus]

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

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.

--
Ricardo

Re: Communication and Design at Guix

[Ludovic Courtès]

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

Re: Communication and Design at Guix

[L p R n d n]

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

Re: Communication and Design at Guix

[zimoun]

Dear,

If I may, I would say that no manual can satisfy every reader; in
terms of rendering (menu, color, etc.) and in terms of content (deep
details or not, etc.).

About the rendering, some of us like to browse with Emacs and
info-mode, other prefer Web-style. There is no general pattern. :-)

About the content, I agree that the GNU manuals are intimidating for
newcomers because they are exhaustive, and the newcomers---as me---are
lost in all the details.
I also agree that someone often finds something in GNU manuals only if
they knows what they is looking for.
However, the GNU manuals are so useful once you are emancipated enough. :-)

An Introduction to Programming in Emacs Lisp spots well the different
kind of reader:
https://www.gnu.org/software/emacs/manual/html_node/eintr/Who-You-Are.html#Who-You-Are
It appears to me really a good companion to the heavy Elisp manual. I
mean one complements the other; depending on the reader's skills and
on they learns.

As a newcomer, what lacks in the Guix documentation are concrete
examples and use cases. They exist but they are scattered: blog post,
Pjotr's docs, etc.
A section with examples should be nice, e.g., some subsection as: Guix
for the impatient, Guix for the Web dev, Guix for the Scientific, Guix
for Pythonista, Guix for the Conda user, etc.
From my opinion, it is in the same direction than the effort about the
videos (current outreachy); if I am understanding well.


All the best,
simon

Re: Communication and Design at Guix

[nly]

[-- Attachment #1: Type: text/plain, Size: 1961 bytes --]

>As a newcomer, what lacks in the Guix documentation are concrete
examples and use cases.

continuing with the emacs example, a guixwiki.org would be awesome as an analog for emacswiki.org. User maintained, quick and short examples with lots of supporting links.

On January 15, 2019 10:36:20 AM UTC, zimoun <zimon.toutoune@gmail.com> wrote:
>Dear,
>
>If I may, I would say that no manual can satisfy every reader; in
>terms of rendering (menu, color, etc.) and in terms of content (deep
>details or not, etc.).
>
>About the rendering, some of us like to browse with Emacs and
>info-mode, other prefer Web-style. There is no general pattern. :-)
>
>About the content, I agree that the GNU manuals are intimidating for
>newcomers because they are exhaustive, and the newcomers---as me---are
>lost in all the details.
>I also agree that someone often finds something in GNU manuals only if
>they knows what they is looking for.
>However, the GNU manuals are so useful once you are emancipated enough.
>:-)
>
>An Introduction to Programming in Emacs Lisp spots well the different
>kind of reader:
>https://www.gnu.org/software/emacs/manual/html_node/eintr/Who-You-Are.html#Who-You-Are
>It appears to me really a good companion to the heavy Elisp manual. I
>mean one complements the other; depending on the reader's skills and
>on they learns.
>
>As a newcomer, what lacks in the Guix documentation are concrete
>examples and use cases. They exist but they are scattered: blog post,
>Pjotr's docs, etc.
>A section with examples should be nice, e.g., some subsection as: Guix
>for the impatient, Guix for the Web dev, Guix for the Scientific, Guix
>for Pythonista, Guix for the Conda user, etc.
From my opinion, it is in the same direction than the effort about the
>videos (current outreachy); if I am understanding well.
>
>
>All the best,
>simon

-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.

[-- Attachment #2: Type: text/html, Size: 2361 bytes --]

Re: Communication and Design at Guix

[Ricardo Wurmus]

nly <nly@disroot.org> writes:

> continuing with the emacs example, a guixwiki.org would be awesome as
> an analog for emacswiki.org. User maintained, quick and short examples
> with lots of supporting links.

Hmm, I have the opposite opinion.  I find the emacswiki to be a great
example for what’s wrong with wikis :)

I’d prefer to add to the documentation that comes with Guix.  It doesn’t
all have to fit into the manual; there can be a tutorial document,
and/or a “cookbook” document — all collectively maintained in the main
repository and matching the very same version of Guix that the user
installed.

I would welcome patches that add a new cookbook document.

--
Ricardo

Re: Communication and Design at Guix

[Giovanni Biscuolo]

[-- Attachment #1: Type: text/plain, Size: 1585 bytes --]

Hi all,

I'm not an expert on "hot to write a reference manual" but I like how
the content is organized in Guix manual and I'd like that all Guix
documentation will remain a coherent set

Ricardo Wurmus <rekado@elephly.net> writes:

> nly <nly@disroot.org> writes:
>
>> continuing with the emacs example, a guixwiki.org would be awesome as
>> an analog for emacswiki.org. User maintained, quick and short examples
>> with lots of supporting links.
>
> Hmm, I have the opposite opinion.  I find the emacswiki to be a great
> example for what’s wrong with wikis :)

i agree with Ricardo verbatim

with all due respect to people involved, I find emacswiki one of the
worst source of information and documentation on Emacs: all is scattered
across many pages and hardly I (an emacs newbie) found
valuable information - most outdated - there

speaking of content organization, we should take inspiration from
https://www.gnu.org/software/emacs/manual/index.html [1]

obviously there is always space for *presentation* enhancements (CSS and
alike) but that's another story

[...]

> I would welcome patches that add a new cookbook document.

...or a FAQ document

should we start a documentation-wishlist.org in maintenance/doc?

(I'm still not sufficiently skilled to help with content, but can help
keep such todo-lists)

[...]

happy hacking!
Giovanni


[1] AFAIK each documented mode or package is part of the official Emacs
distribution while external packages are not documented

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

Re: Communication and Design at Guix

[Ludovic Courtès]

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

Re: Communication and Design at Guix

[swedebugia]

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

> Hi!
>
> Ricardo Wurmus <rekado@elephly.net> skribis:
>> 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 for the clarification :)

I looked into the chicken docs and their html and css. They generate
their examples from source-code with this MIT chicken egg-script: 
http://code.call-cc.org/svn/chicken-eggs/release/4/colorize/trunk/colorize.scm.

To use their approach with parens highlighting we would need to either
depend on chicken and this egg or port it to guile.

I ran it just for fun and got an error as expected. :p

It generates nice html like this:
<pre><tt class="highlight scheme-language"><span class="comment">;; irregex, the regular expression library, is one of the
</span><span class="comment">;; libraries included with CHICKEN.
</span><span class="paren1">(<span class="default">import <span class="paren2">(<span class="default">chicken irregex</span>)</span>
        <span class="paren2">(<span class="default">chicken io</span>)</span></span>)</span>


The CSS magic is this (public domain):
#content .highlight .paren1,#content .highlight .paren2,#content .highlight .paren3,#content .highlight .paren4,#content .highlight .paren5,#content .highlight .paren6 {
    background-color:inherit;
}

#content .highlight .paren1:hover,#content .highlight .paren2:hover,#content .highlight .paren3:hover,#content .highlight .paren4:hover,#content .highlight .paren5:hover,#content .highlight .paren6:hover {
    color:#FFF;
    font-weight:700;
}

#content .highlight .paren1:hover {
    background-color:#DB7859;
}

#content .highlight .paren2:hover {
    background-color:#1B804C;
}

#content .highlight .paren3:hover {
    background-color:#9F214E;
}

#content .highlight .paren4:hover {
    background-color:#DBA059;
}

#content .highlight .paren5:hover {
    background-color:#B64926;
}

#content .highlight .paren6:hover {
    background-color:#64A422;
}

#content .highlight .comment {
    color:#8C8281;
    font-style:italic;
}

Re: Communication and Design at Guix

[Ricardo Wurmus]

swedebugia <swedebugia@riseup.net> writes:

> I looked into the chicken docs and their html and css. They generate
> their examples from source-code with this MIT chicken egg-script: 
> http://code.call-cc.org/svn/chicken-eggs/release/4/colorize/trunk/colorize.scm.
>
> To use their approach with parens highlighting we would need to either
> depend on chicken and this egg or port it to guile.

Are you aware of the guile-syntax-highlight package?

-- 
Ricardo

Re: Communication and Design at Guix

[Julien Lepiller]

Le 2019-01-15 14:56, Ricardo Wurmus a écrit :
> swedebugia <swedebugia@riseup.net> writes:
> 
>> I looked into the chicken docs and their html and css. They generate
>> their examples from source-code with this MIT chicken egg-script:
>> http://code.call-cc.org/svn/chicken-eggs/release/4/colorize/trunk/colorize.scm.
>> 
>> To use their approach with parens highlighting we would need to either
>> depend on chicken and this egg or port it to guile.
> 
> Are you aware of the guile-syntax-highlight package?

Hey, I use it for my blog, but it doesn't generate the same kind
of html:

<span class="syntax-open">(</span><span 
class="syntax-symbol">foo</span><span class="syntax-close">)</span>

So I've just written a bit of scheme to convert that to nested
syntax-paren spans:

<span class="syntax-paren"><span class="syntax-open">(</span><span 
class="syntax-symbol">foo</span><span 
class="syntax-close">)</span></span>

(define (break-paren sxmls)
   (match sxmls
     ('() (values '() '()))
     ((('span ('@ ('class "syntax-close")) _) tag ...)
      (values '((span (@ (class "syntax-close")) ")")) tag))
     ((('span ('@ ('class "syntax-open")) _) tag ...)
      (receive (inside outside)
        (break-paren tag)
        (receive (inside2 outside2)
          (break-paren outside)
          (values (cons `(span (@ (class "syntax-paren")) ,@(cons `(span 
(@ (class "syntax-open")) "(") inside)) inside2) outside2))))
     ((tag ...)
      (receive (inside outside)
        (break-paren (cdr tag))
        (values (cons (car tag) inside) outside)))))

(define (paren-grouper sxmls)
   (match sxmls
     ('() '())
     ((('span ('@ ('class "syntax-open")) _) tag ...)
      (receive (inside outside)
        (break-paren tag)
        (cons `(span (@ (class "syntax-paren")) ,@(cons `(span (@ (class 
"syntax-open")) "(") inside)) (paren-grouper outside))))
     ((tag ...)
      (begin
        (cons (paren-matcher (list (car tag))) (paren-grouper (cdr 
tag)))))))

(define (paren-matcher sxml)
   (match sxml
     ((tag ('@ attrs ...) content ...)
      `(,tag (@ ,attrs) ,@(paren-grouper content)))
     ((tag content ...)
      `(,tag ,@(paren-grouper content)))))

You're supposed to call paren-matcher on a sxml tag. It tries to find
the matching parenthesis for each opening one and wraps the content
inside a span. That's it. You need (ice-9 receive) and (ice-9 match).


Not sure how much of that is actually needed. Maybe there's already an
option to do all that? With a bit of css, the result is here:

https://lepiller.eu/ma-configuration.html

Re: Communication and Design at Guix

[Ludovic Courtès]

Julien Lepiller <julien@lepiller.eu> skribis:

> You're supposed to call paren-matcher on a sxml tag. It tries to find
> the matching parenthesis for each opening one and wraps the content
> inside a span. That's it. You need (ice-9 receive) and (ice-9 match).

I think you should pass it on to David Thompson to consider integration
in guile-syntax-highlight.

Ludo’.

Re: Communication and Design at Guix

[L p R n d n]

Hi,

swedebugia <swedebugia@riseup.net> writes:

> "Ludovic Courtès" <ludo@gnu.org> skrev: (8 januari 2019 18:37:53 CET)
>>Hello,
>>
>>L  p R n  d n    <guix@lprndn.info> skribis:
>>
>>> After taking some time learning Guix and trying to get some new
>>packages
>>> in, I wanted get involved in a slightly different way. I'm not good
>>at
>>> programming and I think my time might be better used participating in
>>> tasks a little more inline with my skills.
>>> The thing is that I find "design" and "communication" (take it in a
>>very broad
>>> way) often a little more complex and delicate to tackle in a group
>>> project. This is why I'm introducing the idea with this mail.
>>
>>This is one of the non-programming activities where Guix needs help so
>>I’m glad you’re offering to contribute!
>>
>>> I think the Guix project could benefit a lot from dealing with the
>>> "rest of the world" and how it wants to show itself. It might even
>>help
>>> clarify some technical decisions if needed. Bonus is that next
>>release
>>> will probably be 1.0 and that it means Guix will get extra attention.
>>>
>>> I have a few things I would like to talk about but, as I don't want
>>to
>>> force aniything on anyone, I wanted to first have your thoughts about
>>this and
>>> eventually what you guix people think would be nice to tackle on. (I
>>> think I saw something about a wiki somewhere for example etc.)
>>
>>I’m not sure we need a wiki.  :-)
>>
>>A very concrete task that could be of interest to you is the “name
>>change” (a bit of a strong word) that we’d like to implement by 1.0.
>>I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
>>confuses things: people visit the web site, they see a “GuixSD” logo
>>and
>>get confused because they were just looking for a package manager, not
>>a
>>whole distro, or they think “GuixSD” is a storage device ;-), things
>>like that.
>>
>>The idea is to bring everything under the “Guix” name.  Most of the
>>time, writing “Guix” is good enough—after all, one can run ‘guix
>>system’
>>on a foreign distro, too.  When we really need to make the distinction,
>>for instance in the manual, we would write “Guix System” to designate
>>what we currently call “GuixSD”.
>>
>>This has implications mostly on the web site and on the manual. 
>>Ricardo
>>sketched web site modifications here:
>>
>>  https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00300.html
>>
>>It would probably have further implications on how we present
>>Guix/GuixSD.
>>
>>WDYT?
>>
>>> By the way, I wanted to start working on the documentation. 
>>> IMHO, it might benefit from a little graphical enhancement for
>>> newcomers. The thing is that it's currently hosted on
>>> gnu.org so it's probably not possible to modify the design. So I
>>wanted
>>> to ask, first, if that's something that would be welcome? What could
>>be
>>> the possibilities? And what would be the technical limitations?
>>
>>The HTML pages at gnu.org/s/guix/manual are generated from Texinfo. 
>>The
>>CSS there is shared with all the GNU manuals, which is nice for
>>consistency.  Ideally modifications of the CSS would be submitted to
>>the
>>GNU webmaster or bug-gnulib@gnu.org (I forgot which one).  However, be
>>aware that you may encounter misplaced conservatism if you take that
>>route, so don’t lose your hair on it.
>>
>>Thanks,
>>Ludo’.
>
> What about guix.info? We can do whatever we want there I suppose and just link
> to it from the gnu site.
>
> Talking about CSS and the manual I would like to add patens highlighting.
> The chicken documentation has this (on mouse over) and it is really nice to be
> able to see how complicated expressions are composed.
>
> Also it would be really nice with a guix style guide apart from the manual and a
> script to go through the code and autodocument from all the docstrings.
> (In the repl ,apropos can do a little something like this) I got this idea from
> php reading the code of dolibarr.
> I'm mentioning this because it is important to know what procedures are where in
> our code for new contributors.

I agree with that too. It could boost how quickly a dev is able to hack
on Guix. Getting faster to the fun part.

Have a nice day,

Lprndn

Re: Communication and Design at Guix

[L p R n d n]

Hello,

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

> Hello,
>
> L  p R n  d n    <guix@lprndn.info> skribis:
>
>> After taking some time learning Guix and trying to get some new packages
>> in, I wanted get involved in a slightly different way. I'm not good at
>> programming and I think my time might be better used participating in
>> tasks a little more inline with my skills.
>> The thing is that I find "design" and "communication" (take it in a very broad
>> way) often a little more complex and delicate to tackle in a group
>> project. This is why I'm introducing the idea with this mail.
>
> This is one of the non-programming activities where Guix needs help so
> I’m glad you’re offering to contribute!
>
>> I think the Guix project could benefit a lot from dealing with the
>> "rest of the world" and how it wants to show itself. It might even help
>> clarify some technical decisions if needed. Bonus is that next release
>> will probably be 1.0 and that it means Guix will get extra attention.
>>
>> I have a few things I would like to talk about but, as I don't want to
>> force aniything on anyone, I wanted to first have your thoughts about this and
>> eventually what you guix people think would be nice to tackle on. (I
>> think I saw something about a wiki somewhere for example etc.)
>
> I’m not sure we need a wiki.  :-)

Yeah, I don't know. Still I think some things would benefit from
not getting lost in the mailing list or IRC. :-/

> A very concrete task that could be of interest to you is the “name
> change” (a bit of a strong word) that we’d like to implement by 1.0.
> I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
> confuses things: people visit the web site, they see a “GuixSD” logo and
> get confused because they were just looking for a package manager, not a
> whole distro, or they think “GuixSD” is a storage device ;-), things
> like that.
>
> The idea is to bring everything under the “Guix” name.  Most of the
> time, writing “Guix” is good enough—after all, one can run ‘guix system’
> on a foreign distro, too.  When we really need to make the distinction,
> for instance in the manual, we would write “Guix System” to designate
> what we currently call “GuixSD”.

Hum. It might just be as easy as getting rid of the GuixSD logo and
wording for the most part. Then we can find a *preferred* way to
designate GuixSD (a Guix system (probably), Guix distro, Guix os).Here,
it's more about making GuixSD "disappear" but we could also just rebrand
GuixSD with some kind of "subtitle": "Guix, the system", derive a logo
from the Guix's one. It depends a lot from what we want to put under the spotlight.

> This has implications mostly on the web site and on the manual.  Ricardo
> sketched web site modifications here:
>
>   https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00300.html
>
> It would probably have further implications on how we present
> Guix/GuixSD.
>
> WDYT?

Yeah, thinking about GuixSD as a derivative is probably the best way to
comprehend it. So give it its own leaf page is probably a good idea. I
would keep all downloads on the same page though and just separate them
visually. But it depends froms what I said previously.

>> By the way, I wanted to start working on the documentation. 
>> IMHO, it might benefit from a little graphical enhancement for
>> newcomers. The thing is that it's currently hosted on
>> gnu.org so it's probably not possible to modify the design. So I wanted
>> to ask, first, if that's something that would be welcome? What could be
>> the possibilities? And what would be the technical limitations?
>
> The HTML pages at gnu.org/s/guix/manual are generated from Texinfo.  The
> CSS there is shared with all the GNU manuals, which is nice for
> consistency.  Ideally modifications of the CSS would be submitted to the
> GNU webmaster or bug-gnulib@gnu.org (I forgot which one).  However, be
> aware that you may encounter misplaced conservatism if you take that
> route, so don’t lose your hair on it.
>
> Thanks,
> Ludo’.

Re: Communication and Design at Guix

[Ricardo Wurmus]

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

>> I’m not sure we need a wiki.  :-)
>
> Yeah, I don't know. Still I think some things would benefit from
> not getting lost in the mailing list or IRC. :-/

If we have a bit of information that’s valuable enough to keep, it
should find its way into the manual.  If there’s no suitable manual
section for that (e.g. one dedicated to examples) then it should be
added.

--
Ricardo

Re: Communication and Design at Guix

[Ludovic Courtès]

Hi,

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

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

[...]

>> A very concrete task that could be of interest to you is the “name
>> change” (a bit of a strong word) that we’d like to implement by 1.0.
>> I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
>> confuses things: people visit the web site, they see a “GuixSD” logo and
>> get confused because they were just looking for a package manager, not a
>> whole distro, or they think “GuixSD” is a storage device ;-), things
>> like that.
>>
>> The idea is to bring everything under the “Guix” name.  Most of the
>> time, writing “Guix” is good enough—after all, one can run ‘guix system’
>> on a foreign distro, too.  When we really need to make the distinction,
>> for instance in the manual, we would write “Guix System” to designate
>> what we currently call “GuixSD”.
>
> Hum. It might just be as easy as getting rid of the GuixSD logo and
> wording for the most part. Then we can find a *preferred* way to
> designate GuixSD (a Guix system (probably), Guix distro, Guix os).Here,
> it's more about making GuixSD "disappear" but we could also just rebrand
> GuixSD with some kind of "subtitle": "Guix, the system", derive a logo
> from the Guix's one. It depends a lot from what we want to put under the spotlight.

The idea is more to have a single “brand”: Guix.  Then “Guix System”
would be a component of Guix, so to speak, similar to GNOME and its
applications.

>> This has implications mostly on the web site and on the manual.  Ricardo
>> sketched web site modifications here:
>>
>>   https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00300.html
>>
>> It would probably have further implications on how we present
>> Guix/GuixSD.
>>
>> WDYT?
>
> Yeah, thinking about GuixSD as a derivative is probably the best way to
> comprehend it. So give it its own leaf page is probably a good idea. I
> would keep all downloads on the same page though and just separate them
> visually. But it depends froms what I said previously.

Sounds reasonable.

Would you like to give it a go?  I suppose the changes to the web site
can be made incrementally, it’s not an all-or-nothing change.  If you’d
like to fiddle with this and you need guidance with the web site
machinery, don’t hesitate to ask on IRC or the ML!

Thanks,
Ludo’.

Re: Communication and Design at Guix

[L p R n d n]

Hey,

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

> Hi,
>
> L  p R n  d n    <guix@lprndn.info> skribis:
>
>> Ludovic Courtès <ludo@gnu.org> writes:
>
> [...]
>
>>> A very concrete task that could be of interest to you is the “name
>>> change” (a bit of a strong word) that we’d like to implement by 1.0.
>>> I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
>>> confuses things: people visit the web site, they see a “GuixSD” logo and
>>> get confused because they were just looking for a package manager, not a
>>> whole distro, or they think “GuixSD” is a storage device ;-), things
>>> like that.
>>>
>>> The idea is to bring everything under the “Guix” name.  Most of the
>>> time, writing “Guix” is good enough—after all, one can run ‘guix system’
>>> on a foreign distro, too.  When we really need to make the distinction,
>>> for instance in the manual, we would write “Guix System” to designate
>>> what we currently call “GuixSD”.
>>
>> Hum. It might just be as easy as getting rid of the GuixSD logo and
>> wording for the most part. Then we can find a *preferred* way to
>> designate GuixSD (a Guix system (probably), Guix distro, Guix os).Here,
>> it's more about making GuixSD "disappear" but we could also just rebrand
>> GuixSD with some kind of "subtitle": "Guix, the system", derive a logo
>> from the Guix's one. It depends a lot from what we want to put under the spotlight.
>
> The idea is more to have a single “brand”: Guix.  Then “Guix System”
> would be a component of Guix, so to speak, similar to GNOME and its
> applications.

Ok, I understand. Just thought about something really quick. Do you
think describing "Guix Sytem" as a system manager, in opposition to
package manager, would be meaningful?

>>> This has implications mostly on the web site and on the manual.  Ricardo
>>> sketched web site modifications here:
>>>
>>>   https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00300.html
>>>
>>> It would probably have further implications on how we present
>>> Guix/GuixSD.
>>>
>>> WDYT?
>>
>> Yeah, thinking about GuixSD as a derivative is probably the best way to
>> comprehend it. So give it its own leaf page is probably a good idea. I
>> would keep all downloads on the same page though and just separate them
>> visually. But it depends froms what I said previously.
>
> Sounds reasonable.
>
> Would you like to give it a go?  I suppose the changes to the web site
> can be made incrementally, it’s not an all-or-nothing change.  If you’d
> like to fiddle with this and you need guidance with the web site
> machinery, don’t hesitate to ask on IRC or the ML!

Yeah I'll try to find some time. ;)

> Thanks,
> Ludo’.


Have a nice day,
Lprndn

Re: Communication and Design at Guix

[Ludovic Courtès]

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

>> The idea is more to have a single “brand”: Guix.  Then “Guix System”
>> would be a component of Guix, so to speak, similar to GNOME and its
>> applications.
>
> Ok, I understand. Just thought about something really quick. Do you
> think describing "Guix Sytem" as a system manager, in opposition to
> package manager, would be meaningful?

In theory yes, but in practice “system manager” is terribly vague and
could mean anything, so I’d rather avoid it.

Ludo’.

Re: Communication and Design at Guix

[George Clemmer]

Hi Lprndn,

I am glad to see your interest in these issues.

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

> Hi,
>
> L  p R n  d n    <guix@lprndn.info> skribis:
>
>> Ludovic Courtès <ludo@gnu.org> writes:
>
> [...]
>
>>> A very concrete task that could be of interest to you is the “name
>>> change” (a bit of a strong word) that we’d like to implement by 1.0.
>>> I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
>>> confuses things: people visit the web site, they see a “GuixSD” logo and
>>> get confused because they were just looking for a package manager, not a
>>> whole distro, or they think “GuixSD” is a storage device ;-), things
>>> like that.
>>>
>>> The idea is to bring everything under the “Guix” name.  Most of the
>>> time, writing “Guix” is good enough—after all, one can run ‘guix system’
>>> on a foreign distro, too.  When we really need to make the distinction,
>>> for instance in the manual, we would write “Guix System” to designate
>>> what we currently call “GuixSD”.
>>
>> Hum. It might just be as easy as getting rid of the GuixSD logo and
>> wording for the most part. Then we can find a *preferred* way to
>> designate GuixSD (a Guix system (probably), Guix distro, Guix os).Here,
>> it's more about making GuixSD "disappear" but we could also just rebrand
>> GuixSD with some kind of "subtitle": "Guix, the system", derive a logo
>> from the Guix's one. It depends a lot from what we want to put under
>> the spotlight.
>
> The idea is more to have a single “brand”: Guix.

Yes a single brand is the way to go. But, piecemeal changes to the web
site are unlikely to get us there unless we work from a unified "Guix
Brand" product description. E.g., earlier I proposed ...

"'Guix' is a software environment manager that creates user environments
that are completely and independently specified by users. Guix users are
never stuck needing software that a Sysadmin can't, won't, or hasn't
installed. A Guix user can run multiple, differing environments
simultaneously and can replicate any environment on any Guix run-time
platform.  Guix provides system-wide environment management when
appropriate to the run-time platform.  Creation, modification, and
upgrade are atomic and roll-back is instantaneous, so Guix users and
sysadmins are never stuck with a broken user environment or system.
Guix implements a functional specification of package, user, and system
configurations using the Scheme language.  Guix complies with the FSF
Four Essential Freedoms and Free System Distribution Guidelines and
provides easy and immediate access to the exact source being run.  By
default, Guix uses pre-built package substitutes from the Guix build
farm and mirrors but users may build any package, or a complete system,
from package developer sources."[1]

> Then “Guix System” would be a component of Guix, so to speak, similar
> to GNOME and its applications.

"Guix System" is a "bad" name for "GuixSD." Why? Because a new user's
first expectation is for "Guix system" to refer to the whole of Guix,
which we want to call "Guix" (referred to as "Guix Brand" below).

But if we call GuixSD the "Guix System", we create a counter-intuitive
thing to explain. E.g., we will be saying, "Our GNU/Linux System
Distribution, 'Guix System' is just one of multiple ways to use 'Guix
Brand', which includes the Guix package manager, for which we also use
the 'Guix Brand' label.

Another "bad" thing about calling it "Guix system" is that when a user
searches "guix system" they hit the 'guix system' "Guix Brand" package
manager' command that, BTW, also generates "Guix VMs".

It will simplify our work if we present GuixSD as simply one of several
Guix download/deployment options. E.g., earlier I suggested ...

"Guix is available on multiple run-time platforms including bare metal
(GuixSD), Virtual Machines (QEMU image), and any GNU/Linux distro (Guix
Binary).[1]"

With this approach, we only need a distinctive label for GuixSD that
doesn't puzzle users to produce reliable search hits on the relevant
parts of our message and documentation. E.g., GuixOS.

HTH - George

[1] https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00444.html

Re: Communication and Design at Guix

[swedebugia]

On 2019-01-16 16:31, George Clemmer wrote:
> Hi Lprndn,
> 
> I am glad to see your interest in these issues.
> 
> Ludovic Courtès <ludo@gnu.org> writes:
> 
>> Hi,
>>
>> L  p R n  d n    <guix@lprndn.info> skribis:
>>
>>> Ludovic Courtès <ludo@gnu.org> writes:
>>
>> [...]
>>
>>>> A very concrete task that could be of interest to you is the “name
>>>> change” (a bit of a strong word) that we’d like to implement by 1.0.
>>>> I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
>>>> confuses things: people visit the web site, they see a “GuixSD” logo and
>>>> get confused because they were just looking for a package manager, not a
>>>> whole distro, or they think “GuixSD” is a storage device ;-), things
>>>> like that.
>>>>
>>>> The idea is to bring everything under the “Guix” name.  Most of the
>>>> time, writing “Guix” is good enough—after all, one can run ‘guix system’
>>>> on a foreign distro, too.  When we really need to make the distinction,
>>>> for instance in the manual, we would write “Guix System” to designate
>>>> what we currently call “GuixSD”.
>>>
>>> Hum. It might just be as easy as getting rid of the GuixSD logo and
>>> wording for the most part. Then we can find a *preferred* way to
>>> designate GuixSD (a Guix system (probably), Guix distro, Guix os).Here,
>>> it's more about making GuixSD "disappear" but we could also just rebrand
>>> GuixSD with some kind of "subtitle": "Guix, the system", derive a logo
>>> from the Guix's one. It depends a lot from what we want to put under
>>> the spotlight.
>>
>> The idea is more to have a single “brand”: Guix.
> 
> Yes a single brand is the way to go. But, piecemeal changes to the web
> site are unlikely to get us there unless we work from a unified "Guix
> Brand" product description. E.g., earlier I proposed ...
> 
> "'Guix' is a software environment manager that creates user environments
> that are completely and independently specified by users. Guix users are
> never stuck needing software that a Sysadmin can't, won't, or hasn't
> installed. A Guix user can run multiple, differing environments
> simultaneously and can replicate any environment on any Guix run-time
> platform.  Guix provides system-wide environment management when
> appropriate to the run-time platform.  Creation, modification, and
> upgrade are atomic and roll-back is instantaneous, so Guix users and
> sysadmins are never stuck with a broken user environment or system.
> Guix implements a functional specification of package, user, and system
> configurations using the Scheme language.  Guix complies with the FSF
> Four Essential Freedoms and Free System Distribution Guidelines and
> provides easy and immediate access to the exact source being run.  By
> default, Guix uses pre-built package substitutes from the Guix build
> farm and mirrors but users may build any package, or a complete system,
> from package developer sources."[1]
> 
>> Then “Guix System” would be a component of Guix, so to speak, similar
>> to GNOME and its applications.
> 
> "Guix System" is a "bad" name for "GuixSD." Why? Because a new user's
> first expectation is for "Guix system" to refer to the whole of Guix,
> which we want to call "Guix" (referred to as "Guix Brand" below).
> 
> But if we call GuixSD the "Guix System", we create a counter-intuitive
> thing to explain. E.g., we will be saying, "Our GNU/Linux System
> Distribution, 'Guix System' is just one of multiple ways to use 'Guix
> Brand', which includes the Guix package manager, for which we also use
> the 'Guix Brand' label.
> 
> Another "bad" thing about calling it "Guix system" is that when a user
> searches "guix system" they hit the 'guix system' "Guix Brand" package
> manager' command that, BTW, also generates "Guix VMs".
> 
> It will simplify our work if we present GuixSD as simply one of several
> Guix download/deployment options. E.g., earlier I suggested ...
> 
> "Guix is available on multiple run-time platforms including bare metal
> (GuixSD), Virtual Machines (QEMU image), and any GNU/Linux distro (Guix
> Binary).[1]"
> 
> With this approach, we only need a distinctive label for GuixSD that
> doesn't puzzle users to produce reliable search hits on the relevant
> parts of our message and documentation. E.g., GuixOS.
> 
> HTH - George
> 
> [1] https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00444.html

+1 Nice work George. 

GuixOS gives us the advantage of OS already being known as a complete
useful separate thing to boot and install (e.g. NixOS, ReactOS, Chrome
OS, iOS, etc.)

Guix is now an octopus with many arms :)

-- 
Cheers 
Swedebugia

Re: Communication and Design at Guix

[L p R n d n]

Hello,

Thanks for your feedbacks!

George Clemmer <myglc2@gmail.com> writes:

> Hi Lprndn,
>
> I am glad to see your interest in these issues.
>
> Ludovic Courtès <ludo@gnu.org> writes:
>
>> Hi,
>>
>> L  p R n  d n    <guix@lprndn.info> skribis:
>>
>>> Ludovic Courtès <ludo@gnu.org> writes:
>>
>> [...]
>>
>>>> A very concrete task that could be of interest to you is the “name
>>>> change” (a bit of a strong word) that we’d like to implement by 1.0.
>>>> I’ll try to summarize.  Currently we have “Guix” and “GuixSD”, and that
>>>> confuses things: people visit the web site, they see a “GuixSD” logo and
>>>> get confused because they were just looking for a package manager, not a
>>>> whole distro, or they think “GuixSD” is a storage device ;-), things
>>>> like that.
>>>>
>>>> The idea is to bring everything under the “Guix” name.  Most of the
>>>> time, writing “Guix” is good enough—after all, one can run ‘guix system’
>>>> on a foreign distro, too.  When we really need to make the distinction,
>>>> for instance in the manual, we would write “Guix System” to designate
>>>> what we currently call “GuixSD”.
>>>
>>> Hum. It might just be as easy as getting rid of the GuixSD logo and
>>> wording for the most part. Then we can find a *preferred* way to
>>> designate GuixSD (a Guix system (probably), Guix distro, Guix os).Here,
>>> it's more about making GuixSD "disappear" but we could also just rebrand
>>> GuixSD with some kind of "subtitle": "Guix, the system", derive a logo
>>> from the Guix's one. It depends a lot from what we want to put under
>>> the spotlight.
>>
>> The idea is more to have a single “brand”: Guix.
>
> Yes a single brand is the way to go. But, piecemeal changes to the web
> site are unlikely to get us there unless we work from a unified "Guix
> Brand" product description. E.g., earlier I proposed ...
>
> "'Guix' is a software environment manager that creates user environments
> that are completely and independently specified by users. Guix users are
> never stuck needing software that a Sysadmin can't, won't, or hasn't
> installed. A Guix user can run multiple, differing environments
> simultaneously and can replicate any environment on any Guix run-time
> platform.  Guix provides system-wide environment management when
> appropriate to the run-time platform.  Creation, modification, and
> upgrade are atomic and roll-back is instantaneous, so Guix users and
> sysadmins are never stuck with a broken user environment or system.
> Guix implements a functional specification of package, user, and system
> configurations using the Scheme language.  Guix complies with the FSF
> Four Essential Freedoms and Free System Distribution Guidelines and
> provides easy and immediate access to the exact source being run.  By
> default, Guix uses pre-built package substitutes from the Guix build
> farm and mirrors but users may build any package, or a complete system,
> from package developer sources."[1]

Yeah, I didn't totally get the single "brand" Guix, at first. ;)
This paragraph is nice! It's probably usable as is but I think it could
benefits from a little refactoring (multiple parts by usecase or
possible user?). I'll try to give it a go if you don't mind.

>> Then “Guix System” would be a component of Guix, so to speak, similar
>> to GNOME and its applications.
>
> "Guix System" is a "bad" name for "GuixSD." Why? Because a new user's
> first expectation is for "Guix system" to refer to the whole of Guix,
> which we want to call "Guix" (referred to as "Guix Brand" below).
>
> But if we call GuixSD the "Guix System", we create a counter-intuitive
> thing to explain. E.g., we will be saying, "Our GNU/Linux System
> Distribution, 'Guix System' is just one of multiple ways to use 'Guix
> Brand', which includes the Guix package manager, for which we also use
> the 'Guix Brand' label.
>
> Another "bad" thing about calling it "Guix system" is that when a user
> searches "guix system" they hit the 'guix system' "Guix Brand" package
> manager' command that, BTW, also generates "Guix VMs".
>
> It will simplify our work if we present GuixSD as simply one of several
> Guix download/deployment options. E.g., earlier I suggested ...
>
> "Guix is available on multiple run-time platforms including bare metal
> (GuixSD), Virtual Machines (QEMU image), and any GNU/Linux distro (Guix
> Binary).[1]"
>
> With this approach, we only need a distinctive label for GuixSD that
> doesn't puzzle users to produce reliable search hits on the relevant
> parts of our message and documentation. E.g., GuixOS.

I understand. 
Currently, I'm searching for some kind of one liner to describe Guix.
Something that quickly describe what Guix is.
In your previous paragraph you use "software environment manager".
Personnaly, I can't say if it works, I don't think I have the necessary
knowledge to get it. If other guix users thinks it's easily
understandable it should be ok. Otherwise, I was more with things like
this:

Guix is ...

... a package and system manager. (A seen previously, system manager is
too wide)
... a package manager and machine administrator.
... a package and machine administrator.
... a package and environment manager. 

WDYT? If anyone has an idea, don't be shy :)

I'd like to keep the "package manager" part as it'll probably ring a
bell to any linux user and helps understand the not so familiar part
(system/environment dealing).


> HTH - George
>
> [1] https://lists.gnu.org/archive/html/guix-devel/2018-01/msg00444.html

Have a nice day,

Lprndn

Re: Communication and Design at Guix

[Ricardo Wurmus]

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

> Guix is ...
>
> ... a package and system manager. (A seen previously, system manager is
> too wide)
> ... a package manager and machine administrator.
> ... a package and machine administrator.
> ... a package and environment manager.
>
> WDYT? If anyone has an idea, don't be shy :)

“administrator” is generally understood to be a person (as in “system
administrator”).  “environment manager” is just as vague as “system
manager”, in my opinion — “everything is the environment!”.  It only
makes sense to people who are already familiar with the term
“environment” in a computing context.

That’s the advantage the word “package manager” has — it’s already a
well-established term, for better or worse.

> I'd like to keep the "package manager" part as it'll probably ring a
> bell to any linux user and helps understand the not so familiar part
> (system/environment dealing).

Right, that’s what I meant.
We are underselling Guix, though, if we keep referring to it as a
“package manager”, because people’s familiarity with other package
managers may make them think in smaller terms.

FWIW, I’m with Ludo here with regards to “Guix” as the “single brand”.
I disagree with this part that George wrote:

> "Guix System" is a "bad" name for "GuixSD." Why? Because a new user's
> first expectation is for "Guix system" to refer to the whole of Guix,
> which we want to call "Guix" (referred to as "Guix Brand" below).

In my experience “… system” is not generally used to describe a tool’s
full set of features.  I think “Guix System” is just the right term for
everything that Guix generates or operates on with the “guix system” set
of commands.  “GuixOS” is, in my opinion, a pretty terrible name (I’m
also not a fan of all the other “…OS” names out there) and it needlessly
keeps the confusion between “Guix, the tool” and “Guix, the system”
alive.

--
Ricardo

Re: Communication and Design at Guix

[swedebugia]

On 2019-01-17 12:10, Ricardo Wurmus wrote:
> 
> L p R n d n <guix@lprndn.info> writes:
> 
>> Guix is ...
>>
>> ... a package and system manager. (A seen previously, system manager is
>> too wide)
>> ... a package manager and machine administrator.
>> ... a package and machine administrator.
>> ... a package and environment manager.
>>
>> WDYT? If anyone has an idea, don't be shy :)
> 
> “administrator” is generally understood to be a person (as in “system
> administrator”).  “environment manager” is just as vague as “system
> manager”, in my opinion — “everything is the environment!”.  It only
> makes sense to people who are already familiar with the term
> “environment” in a computing context.
> 
> That’s the advantage the word “package manager” has — it’s already a
> well-established term, for better or worse.
> 
>> I'd like to keep the "package manager" part as it'll probably ring a
>> bell to any linux user and helps understand the not so familiar part
>> (system/environment dealing).
> 
> Right, that’s what I meant.
> We are underselling Guix, though, if we keep referring to it as a
> “package manager”, because people’s familiarity with other package
> managers may make them think in smaller terms.
> 
> FWIW, I’m with Ludo here with regards to “Guix” as the “single brand”.
> I disagree with this part that George wrote:
> 
>> "Guix System" is a "bad" name for "GuixSD." Why? Because a new user's
>> first expectation is for "Guix system" to refer to the whole of Guix,
>> which we want to call "Guix" (referred to as "Guix Brand" below).
> 
> In my experience “… system” is not generally used to describe a tool’s
> full set of features.  I think “Guix System” is just the right term for
> everything that Guix generates or operates on with the “guix system” set
> of commands.  “GuixOS” is, in my opinion, a pretty terrible name (I’m
> also not a fan of all the other “…OS” names out there) and it needlessly
> keeps the confusion between “Guix, the tool” and “Guix, the system”
> alive.

Interesting.

So if we go with "Guix System" would the following sentences be meaningful?

"Is your operating system running Guix?" (ambiguous)

"Which operating system do you use? Guix System."
"Are you on Guix System?"
"Which version of Guix System are you using?" (we should really have 
something like lsb_release -a output this term)
"How did you install your Guix System?"
"Can I dual-boot Guix System and Parabola GNU/Linux?"

"A: My Guix System runs Linux. B: Oh, I use the Hurd on mine!"
"I love the R.M. Stallman picture that is on my Guix System during 
boot!" :D (https://wallup.net/wallpapers/richard-stallman/)

"My Guix System performs really well"
"Since I switched my operating system to Guix System I have not looked back"
"I love my Guix System!"
"Guix helps me get things done instead of losing myself in the details 
of dependencies and stuff when coding"
"Guix makes it easy for me to sandbox my browser so I can surf without 
worrying too much"
"Guix System boots a little slower than XX but it is worth the wait!"
"I really like the roll-back provided by Guix System when I end up in a 
broken state" (geek version)
"I really like the roll-back provided by Guix System when my pc won't 
boot and just goes black so I can't use the mouse or log in." (non-geek 
version)
"I recommend Guix System because it makes it easy to copy your friends 
OS setup so that you can get to all the fun parts quickly without 
worrying about installing this or that - everything is there 
out-of-the-box!".

If not please comment.

-- 
Cheers Swedebugia

Re: Communication and Design at Guix

[L p R n d n]

Hello,

swedebugia <swedebugia@riseup.net> writes:

> On 2019-01-17 12:10, Ricardo Wurmus wrote:
>>
>> L p R n d n <guix@lprndn.info> writes:
>>
>>> Guix is ...
>>>
>>> ... a package and system manager. (A seen previously, system manager is
>>> too wide)
>>> ... a package manager and machine administrator.
>>> ... a package and machine administrator.
>>> ... a package and environment manager.
>>>
>>> WDYT? If anyone has an idea, don't be shy :)
>>
>> “administrator” is generally understood to be a person (as in “system
>> administrator”).  “environment manager” is just as vague as “system
>> manager”, in my opinion — “everything is the environment!”.  It only
>> makes sense to people who are already familiar with the term
>> “environment” in a computing context.
>>
>> That’s the advantage the word “package manager” has — it’s already a
>> well-established term, for better or worse.
>>
>>> I'd like to keep the "package manager" part as it'll probably ring a
>>> bell to any linux user and helps understand the not so familiar part
>>> (system/environment dealing).
>>
>> Right, that’s what I meant.
>> We are underselling Guix, though, if we keep referring to it as a
>> “package manager”, because people’s familiarity with other package
>> managers may make them think in smaller terms.
>>
>> FWIW, I’m with Ludo here with regards to “Guix” as the “single brand”.
>> I disagree with this part that George wrote:
>>
>>> "Guix System" is a "bad" name for "GuixSD." Why? Because a new user's
>>> first expectation is for "Guix system" to refer to the whole of Guix,
>>> which we want to call "Guix" (referred to as "Guix Brand" below).
>>
>> In my experience “… system” is not generally used to describe a tool’s
>> full set of features.  I think “Guix System” is just the right term for
>> everything that Guix generates or operates on with the “guix system” set
>> of commands.  “GuixOS” is, in my opinion, a pretty terrible name (I’m
>> also not a fan of all the other “…OS” names out there) and it needlessly
>> keeps the confusion between “Guix, the tool” and “Guix, the system”
>> alive.
>
> Interesting.
>
> So if we go with "Guix System" would the following sentences be meaningful?
>
> "Is your operating system running Guix?" (ambiguous)
>
> "Which operating system do you use? Guix System."
> "Are you on Guix System?"
> "Which version of Guix System are you using?" (we should really have something
> like lsb_release -a output this term)
> "How did you install your Guix System?"
> "Can I dual-boot Guix System and Parabola GNU/Linux?"
>
> "A: My Guix System runs Linux. B: Oh, I use the Hurd on mine!"

I like this.
I would go a little further in terms of branding. If we go with this, I
think speaking of "a Guix system" instead of "the Guix System" (if it's
a noun, it's a brand so we would end up with the same problem that we
have with GuixSD).
"a Guix system" aknowledge the fact that Guix is almost a "system
builder" (VMs, containers, computers, clusters?).

I know Ludovic wasn't fond of "system" but we could replace the word
with anything else if someone find something more appropriate.

Plus, I had sone thoughts about how Guix doesn't fit really well within
the usual "linux distribution" definition. (I think it's unfortunately disadvantaging Guix in reviews, for example.)
I find that speaking of Guix in those terms, even if it doesn't explain
anything, at least gives some hints. I mean, at some point, changing of
channel can almost be like changing distro...

> "I love the R.M. Stallman picture that is on my Guix System during boot!" :D
> (https://wallup.net/wallpapers/richard-stallman/)
>
> "My Guix System performs really well"
> "Since I switched my operating system to Guix System I have not looked back"
> "I love my Guix System!"
> "Guix helps me get things done instead of losing myself in the details of
> dependencies and stuff when coding"
> "Guix makes it easy for me to sandbox my browser so I can surf without worrying
> too much"
> "Guix System boots a little slower than XX but it is worth the wait!"
> "I really like the roll-back provided by Guix System when I end up in a broken
> state" (geek version)
> "I really like the roll-back provided by Guix System when my pc won't boot and
> just goes black so I can't use the mouse or log in." (non-geek version)
> "I recommend Guix System because it makes it easy to copy your friends OS setup
> so that you can get to all the fun parts quickly without worrying about
> installing this or that - everything is there out-of-the-box!".
>
> If not please comment.

Have a nice day,

Lprndn