Re: Enabling contribution through documentation

[Samuel Christie]

Ekaitz Zarraga <ekaitz@elenq.tech> 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