Re: Guix Documentation Meetup

[Matt]

I want to be a part of this.  I feel like I've been rubbing two sticks together 
while it seems some people out there have Zippo lighters. A real-time 
conversation, some paired programming, or simply looking over the shoulder of 
someone who knows what they're doing would go a long way.  I have been trying 
to learn and share by way of case studies: www.excalamus.com.  My hope is that 
these could one day be adapted for the manual, or at least prep me for making 
meaningful contributions to the official documentation.  I have several more 
studies that are unpublished.

I share many of the same challenges others have experienced, certainly with 
Guile.

These are things I'm interested in helping with:

* defining terms

  A glossary, improved indexing (which is there), and more references (also 
present), are things I want to help with.

  For example, I've spent the past few days' free time trying to understand how 
to install an old version of ungoogled-chromium, required for Jitsi. To do this 
required 1) knowing what a profile is and 2) knowing the syntax of "sourcing".  
First, a profile is mentioned in passing several times in the manual as a 
directory. Yet, the guix package --profile option requires a *file* be 
specified.  (yes, a directory is a file, but guix complains if you pass a 
directory). So, is a profile a file or a directory? After much poking around, I 
found that the file specified by the --profile option is a symlink. This 
symlink points to another symlink (specifying the generation?), which in turn 
appears to point to the directory of packages . So, a profile *is* a directory, 
but, depending on how you look at it, it may be a file. Second, to activate the 
profile requires "sourcing" $GUIX_PROFILE/etc/profile (again, is a profile a 
file or a directory?). Some parts of the documentation give this as:

            GUIX_PROFILE="$HOME/.guix-profile" . "$GUIX_PROFILE/etc/profile"

  Nevermind having to look up what was meant by "sourcing", I did that. But it 
turns out that there are two syntaxes for it: the one above and the more clear 
`source "$GUIX_PROFILE/etc/profile"`. Of course, with my luck, that wasn't made 
clear with the resources I found. It took me far too long to see how what I 
found on the open web corresponded to the manual.

* meaning/consequences/significance

  Knowing words without understanding the consequences of their meaning is just 
memorizing jargon. A profile is a directory? So what? Is that significant or 
just trivia? I still don't know.  Sometimes I think I'm reading about the Turbo 
Encabulator (https://www.youtube.com/watch?v=Ac7G7xOG2Ag)

* context/workflows

  I want to help show what it means for Guix to be imperative and declarative.  
Each has a different workflow, it seems, and the manual mixes those together. 
The context isn't always clear.

  Guix is flexible.  It can be complicated, but isn't by necessity.  I've been 
able to get by for nearly a year doing, more or less, guix pull, guix package 
-u, and occasionally guix system reconfigure (with a few guix installs thrown 
in :) Almost all the complex stuff has been from my choice to learn and do more.

  The simple daily workflows aren't apparent to me from the documentation. I 
don't need to code a config or define packages or set up channels or profiles 
or do any of that unless I want to? It took a bit of reading for me to realize, 
that's it?  I think there's a big focus on what can be done with Guix and not 
much said about the boring routine stuff. As a new user (even as a somewhat 
less new user), that's what I need first: I need security that my system will 
work, not crash or destroy my data and not consume my life *unless I choose for 
it to*. Isn't that really what Guix has to offer? Show me.

* navigation/discoverablity

  Guix is described as "the Emacs of distros".  To me Emacs, besides embodying 
freedom, means self-documenting. I wouldn't be a professional programmer 
without Emacs. It nurtures me by answering questions, giving examples, and 
scaffolding learning.  Emacs expands the zone of proximal development 
(https://en.wikipedia.org/wiki/Zone_of_proximal_development) and ensures I can 
achieve what I couldn't before.

  Guix is poised to do the same. However, the documentation and my difficulty 
navigating it is a huge problem for me.

  Others have touched on it when talking about Guile.

  - Is this symbol from Guile or Guix?
  - What does it do?
  - How is it used?
  - How many steps are required for someone to answer these questions?
    (answer: not one like, C-h f. Instead, it might be days searching the 
mailing list, getting familiar with IRC, and being lucky with timing and and 
experimenting)
  - Geiser seems great. How the f*** does it help me answer these
    questions? Wait, what problem am I trying to solve again?

  I love the info system.  Google has nothing on the info reader.  Yet even the 
info system's ability to overcome the documentation trilemma is strained.

  The documentation trilemma is:

    Intelligible, comprehensive, and discoverable: Pick two.

  I feel Guix does pretty well on being comprehensive. And, despite some rough 
spots, it's largely intelligible.

  Guix fails for me on discoverablity.  Can I quickly find the answer to my 
question *and know that I've found it?* That's why I think defining terms, 
focusing on their significance, and providing context through workflows can 
help.

  Discoverablity is also a technical problem.  I want a C-h f for Guix. That's 
something I think Guix and it's community is well positioned to solve, what 
with all these reproducible environments, Emacs users, and what not.  I'd love 
to help that come to fruition.

I can write and publish all day on my blog, but if it's not discoverable and, 
more importantly, not correct, it's not helping anyone.  I, and people like me, 
need help from experts.  That's why I'm so excited about this meet up.  I know 
I can string some words together enough to be understandable.  But is what I'm 
saying helpful?

One final question:

  How might announcements of the "Guix Documentation Meetup" (and "Guix 
Packaging Meetup)" be made more prominent?

I check the mailing list from time to time, but missed the announcements 
because they were buried.  Maybe meetings could be announced on info-guix?  If 
they become regular, maybe put them on https://guix.gnu.org/en/contribute/?  
FWIW, I'm willing to be present so that a documentation meetup could run 
monthly. I'm an FSF member and could use the FSF Jitsi service if I needed to 
host it.  I've not used Big Blue Button before.

Sometimes I wonder why I'm choosing to struggle to learn Guix.  The reason I 
choose to persevere is that Guix could be like Emacs, software for a lifetime.  
That's something I'm willing to invest in.