Re: Enabling contribution through documentation

[Samuel Christie via "Development of GNU Guix and the GNU System distribution." <guix-devel@gnu.org>]

Hello Matt; sorry, I've been distracted and almost missed your 
reply a few weeks ago.

Matt <matt@excalamus.com> writes:

> [...] I tried to write a tutorial on packaging GNU Hello. 
> Really, if I were to look over the shoulder of someone packaging 
> GNU Hello, what would it look like? Why are they doing what 
> they're doing in addition to what and how. It's not obvious at 
> all. The Cookbook touches on GNU Hello.  However, it's hard to 
> see how someone new to the details of Guix packaging, such as 
> myself, is supposed to go from 'Section 2.1.1 A “Hello World” 
> package' to actually packaging something in the wild. All paths 
> inevitably lead to the Guile manual.

Yes, there are several layers of complexity at play: building the 
target package (not easy when all dependencies must also be 
packaged), and specifying the package in Guile.

I'm not that uncomfortable with scheme, though I don't think I 
fully understand g-expressions yet. It would be easier if I could 
get Geiser working for looking up symbols, but if the docs were 
better I suppose I wouldn't have to read the code.

I have successfully packaged some of my own things, trying to use 
guix for managing dev environments; it's not too bad for some 
things, but gets much more complicated when I have to step outside 
the comfort zone of directly using existing packages and build 
systems as inputs.  The other major thing I'm not yet familiar 
with is the patch submission and management process; not that I 
have anything patch-worthy yet, but it is a hurdle.

> Packaging is inherently complex. It requires *at least* knowing 
> something about Unix-like systems, build systems, and details of 
> software development ranging from general programming concepts 
> to specific applications to all the surrounding tooling.

I think it would be fair to assume minimal competence with using a 
shell. Everything else should be given as clear, exact steps to 
take ('mkdir package' not 'make a directory for your package'), so 
that even someone who knows nothing can perform the steps and 
produce the result.

> A common assumption is that "they don't have to know anything 
> before getting started".  Unfortunately, this is not true. 
> Fortunately, we can often abstract this away by giving only the 
> necessary information (not easy to do!) for whatever we're 
> explaining and handing off details to another resource. This is 
> where the Guile documentation fails Guix.

I think of tutorials as exposure rather than explanation, so the 
tutorial itself shouldn't need to explain much or rely on external 
resources. However, once the reader has finished the tutorial, 
they should be able to look up the steps they were exposed to. 
That is what the rest of the documentation is for, so I agree it 
should be improved. 

It's less clear how to "fix the documentation" than "write a 
tutorial" though. Maybe we can start with the tutorial, then 
improve the documentation for everything it used?

> I'd be happy to work alongside you.

Cool! I'm going to be pretty distracted this week, but we could 
start working on it asynchronously. Any thoughts on process? Maybe 
we could have a repo managed the same way Guix is, so I can learn 
that at the same time. (That is, emails for discussion and patches 
to the tutorial)
How hard would that be to get or set up? That could also be the 
'practice repo' people doing the tutorial would use for the final 
submission parts.

After that, I think the first step is picking an easy but 
non-trivial package to do. Maybe it should be one that's already 
been packaged... I went through a list of packages that I wished 
Guix had, and sadly none of them were easy enough for me to do. My 
first choice was INN (a Usenet server), but it has multiple 
service dependencies I wasn't sure how to handle. My other choices 
were apparently in Rust, which always has waaay too many deps. We 
could also do a better Hello tutorial. Thoughts?

Thanks,
-Samuel