Re: Enabling contribution through documentation

[Matt]

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.