Re: Guix Documentation Meetup

[Matt <matt@excalamus.com>]

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.