Re: Enabling contribution through documentation

[Matt <matt@excalamus.com>]

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.