Re: Enabling contribution through documentation
On Mon, 06 Nov 2023 23:43:07 +0100 Samuel Christie wrote --- > > Hello Matt; sorry, I've been distracted and almost missed your reply a few > weeks ago. Not a problem! I've been distracted, too. :) > 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? A central repo makes sense. I'm open to exchanging patches over email rather than doing PRs. If it's okay with the Guix mailing list, I would be happy to have that exchange here so that others may observe, comment, and contribute. I've set up a repo here: https://codeberg.org/excalamus/guix-packaging-tutorial/src/branch/master/guix-packaging-tutorial.org > 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? I think we should do a more detailed Hello tutorial. It is already referenced in the cookbook, it's non-trivial, and this is the use case it was created for. The package definition already exists (gnu/packages/base.scm). Some words on the document: I'd like to see the finished tutorial included in the cookbook. For that, it needs to be written in Texinfo. It's currently in Org. That's simply what I'm most familiar with and the format my notes were in. Org exports to Texinfo and info. While I'm sure the conversion is imprecise, sticking with Org allows me (at least) to write more easily. It's familiar and generates an (approximate) info file. My intent is to focus on explaining the topic and worry about the details of Texinfo later. Otherwise, Org provides a practical benefit: it embeds "live" source blocks. We can run all our shell calls from the document. My hope is that this will keep the source code and shell call snippets accurate. For anyone unfamiliar with Org, I've heavily annotated the document with explanations about how to navigate, edit, and transform it to other formats. If that's too much, that's okay. Just edit the text and we can take care of any markup syntax later. I'm excited to work on this with you and anyone else. I'm curious what your thoughts are :)
Re: Enabling contribution through documentation
Hello Matt; sorry, I've been distracted and almost missed your
reply a few weeks ago.
Matt 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
Re: Enabling contribution through documentation
One elephant was already spoken about. Your message points toward another: the Guile documentation. The Guile documentation needs significant editing. This is a problem because Guix is forever bound to Guile. For every benefit Guix gains from Guile, it also suffers by inheriting its shortcomings. On Mon, 25 Sep 2023 17:13:58 +0200 Samuel Christie via "Development of GNU Guix and the GNU System distribution." wrote --- > My recommendation consists of three parts: > 1. Write a clear tutorial > ... > Such a tutorial would be helpful for onboarding new contributors > because they don't have to know anything before getting started, > just start at the beginning and follow the steps. The tutorial I > was envisioning would work through the steps of writing a simple > package, testing it, then submitting the patches. I tried this and reached the conclusion that it's not possible without addressing shortcomings in the Guile documentation. Specifically, 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. 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. 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. For example, trying to understand (source (origin (method url-fetch) ... )), I looked at the Guix documentation. The Guix documentation says, #+begin_quote 'method' A monadic procedure that handles the given URI. https://guix.gnu.org/en/manual/devel/en/html_node/origin-Reference.html #+end_quote I mistook 'method' to be a procedure that takes a URI. But, no, it's a data type. Several problems jump out to me: 1. The documentation assumes you understand how it's laid out. Unless I missed it, there's no section explaining conventions used by the manual. For example, https://www.gnu.org/software/emacs/manual/html_node/elisp/Format-of-Descriptions.html 2. There is not a clear way, even within Emacs, to figure out what 'method' is. You *must* read the Guix manual. This is the other elephant, the shortcomings of editors. 3. How, really, does someone who doesn't know what is meant by "Data Type" in this context supposed to get that information? How are they to understand what's significant and what's not? Trying to answer this inevitably leads to the Guile documentation. > Would any of you more > experienced developers be willing to "shepherd" me through this > process, and help set up the test environment, etc.? I'd be happy to work alongside you. I'd also be happy to discuss the Guile docs in that mailing list.
Re: Enabling contribution through documentation
Ekaitz Zarraga writes: An option is to make some kind of user-story based documentation might help? As a long-time wannabe-contributor who has been intimidated by the unfamiliar process, I agree with this statement. In fact, (to acknowledge the other more controversial branch of this conversation), I am already an avid user of emacs and plain-text email, so they do not in the least discourage me from contributing. The "difficulties" of editing s-expressions are non-issues for me; I have been using guix as both a daily driver and headless server for a while, and occasionally edit system definitions and even code snippets using mediocre editors like nano without difficulty. That said, I never quite figured out a good development environment and workflow for building packages or hacking on guix itself. Some of that is on me, but I think there is probably room for improvement in both the tools and documentation. However, the unfamiliar process and my cautious personality fearing I might "mess something up" or "bother somebody" have been the biggest barriers to getting started. And last I checked there was not really a tutorial or "safe zone" for practicing to help overcome those challenges. I have actually been planning to start pushing through and writing up a tutorial as I go, and signing up for the guix-devel mailing list again was a step in that direction, so this discussion is rather timely. My recommendation consists of three parts: 1. Write a clear tutorial 2. Offer a "test environment" for new users to practice in 3. Refine documentation into clearer 'how-to' and 'reference' material My current thoughts are building off the 'theory of documentation' described here: https://documentation.divio.com/index.html (1) According to this theory, tutorials are learning experiences that that don't explain much, but simply guide the newbie with step-by-step directions they can follow as-is. We can probably adapt the sourcehut git + email tutorial for part of that purpose: https://git-send-email.io/ Such a tutorial would be helpful for onboarding new contributors because they don't have to know anything before getting started, just start at the beginning and follow the steps. The tutorial I was envisioning would work through the steps of writing a simple package, testing it, then submitting the patches. I also thought it would be neat if we could have a more difficult version assigns outdated packages for upgrading (could even have a leaderboard and make a game out of it), but that's probably a different project. (2) The test environment idea is based partly on the sourcehut tutorial, and at simplest is a separate mailing list that people can send test attempts to. Other people could subscribe and reply with comments on how to fix things, or we could (eventually) automate it to return feedback instantly. Ideally this environment would be as close to the real one as possible, but I'm not sure what that would mean exactly. (3) The third point is a longer term goal for cleaning up the existing documentation, which is a mixture of all four kinds. For example, the 'Sending a patch series' page is written casually like a tutorial but abstractly covers several ways of doing it instead of guiding with concrete steps to achieve a specific goal. Unfortunately, this point is a lot of work and a much longer term goal, and I'm not really prepared or motivated to do all of it myself. I'm just mentioning it here as a potential path toward better documentation. Now, for a proposal / call to action: I intended to start working on the tutorial by myself soon anyway, but I am more likely to be motivated and successful if someone else cared about what I was working on. Would any of you more experienced developers be willing to "shepherd" me through this process, and help set up the test environment, etc.? Thanks, -shcv
