From: Samuel Christie via "Development of GNU Guix and the GNU System distribution." <guix-devel@gnu.org>
To: Ekaitz Zarraga <ekaitz@elenq.tech>
Cc: MSavoritias <email@msavoritias.me>, guix-devel@gnu.org
Subject: Re: Enabling contribution through documentation
Date: Mon, 25 Sep 2023 11:13:58 -0400 [thread overview]
Message-ID: <87h6niffpl.fsf_-_@sdf.org> (raw)
In-Reply-To: <A_E83JQHee_vqSG9pyZQEzD8DTbs3vErkBd716tUtfF7eHODt5WBYdKUO5RKtCrmqOHcOqRVRktcWZ7LwBZ_2DS4koWv1VgKbDk9XPXGnNE=@elenq.tech> (Ekaitz Zarraga's message of "Fri, 22 Sep 2023 17:28:41 +0000")
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
next prev parent reply other threads:[~2023-09-26 22:46 UTC|newest]
Thread overview: 267+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-08-23 16:25 How can we decrease the cognitive overhead for contributors? Katherine Cox-Buday
2023-08-23 17:27 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
2023-08-23 18:03 ` Andreas Enge
2023-08-25 8:07 ` Attila Lendvai
2023-08-25 9:16 ` Andreas Enge
2023-08-25 9:57 ` Attila Lendvai
2023-08-25 23:56 ` Katherine Cox-Buday
2023-08-25 14:44 ` Wilko Meyer
2023-08-26 14:37 ` Liliana Marie Prikler
2023-08-27 12:07 ` Attila Lendvai
2023-08-27 13:57 ` Saku Laesvuori
2023-08-27 17:08 ` Liliana Marie Prikler
2023-08-29 10:04 ` MSavoritias
2023-08-29 11:05 ` Giovanni Biscuolo
2023-09-05 15:33 ` Simon Tournier
2023-09-05 19:16 ` Csepp
2023-09-05 20:43 ` Simon Tournier
2023-08-29 3:00 ` Maxim Cournoyer
2023-09-05 16:01 ` Simon Tournier
2023-09-05 17:01 ` Katherine Cox-Buday
2023-09-05 18:18 ` Liliana Marie Prikler
2023-09-05 18:40 ` (
2023-09-05 20:43 ` Liliana Marie Prikler
2023-09-05 22:04 ` wolf
2023-09-06 18:42 ` Liliana Marie Prikler
2023-09-08 15:39 ` Ricardo Wurmus
2023-09-08 22:56 ` Liliana Marie Prikler
2023-09-06 9:41 ` Josselin Poiret
2023-09-08 14:20 ` Ricardo Wurmus
2023-09-10 9:35 ` Efraim Flashner
2023-09-11 10:34 ` Giovanni Biscuolo
2023-09-06 20:10 ` Wojtek Kosior via Development of GNU Guix and the GNU System distribution.
2023-09-17 8:01 ` MSavoritias
2023-09-07 20:38 ` Katherine Cox-Buday
2023-09-07 20:52 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
2023-09-17 8:07 ` MSavoritias
2023-09-05 23:41 ` brian via Development of GNU Guix and the GNU System distribution.
2023-09-06 16:53 ` Liliana Marie Prikler
2023-09-06 17:52 ` Vagrant Cascadian
2023-09-06 18:27 ` Maxim Cournoyer
2023-09-06 18:49 ` Christopher Baines
2023-09-08 9:16 ` Giovanni Biscuolo
2023-09-08 16:56 ` Liliana Marie Prikler
2023-09-06 19:11 ` Liliana Marie Prikler
2023-09-05 22:57 ` Simon Tournier
2023-09-06 2:34 ` Katherine Cox-Buday
2023-09-06 9:07 ` Simon Tournier
2023-09-07 20:39 ` Katherine Cox-Buday
2023-09-09 12:32 ` Simon Tournier
2023-09-11 12:19 ` Giovanni Biscuolo
2023-09-12 15:35 ` Katherine Cox-Buday
2023-09-12 15:35 ` Katherine Cox-Buday
2023-09-09 17:14 ` Liliana Marie Prikler
2023-09-11 12:37 ` Giovanni Biscuolo
2023-09-11 21:25 ` Csepp
2023-09-12 9:09 ` Giovanni Biscuolo
2023-09-12 11:09 ` Csepp
2023-09-12 14:51 ` Maxim Cournoyer
2023-09-17 12:39 ` MSavoritias
2023-09-08 10:25 ` Giovanni Biscuolo
2023-09-06 19:01 ` Liliana Marie Prikler
2023-09-08 9:53 ` Giovanni Biscuolo
2023-09-08 11:28 ` Ricardo Wurmus
2023-09-08 12:40 ` Giovanni Biscuolo
2023-09-12 16:05 ` Katherine Cox-Buday
2023-09-12 16:05 ` Katherine Cox-Buday
2023-09-13 7:57 ` Simon Tournier
2023-09-13 9:28 ` Simon Tournier
2023-09-12 16:08 ` Katherine Cox-Buday
2023-09-12 16:08 ` Katherine Cox-Buday
2023-09-08 12:09 ` Efraim Flashner
2023-09-08 16:54 ` Giovanni Biscuolo
2023-09-06 2:49 ` Maxim Cournoyer
2023-09-06 22:16 ` kiasoc5
2023-09-08 15:27 ` Ricardo Wurmus
2023-09-08 19:22 ` Liliana Marie Prikler
2023-09-08 20:37 ` Ricardo Wurmus
2023-09-12 16:18 ` Katherine Cox-Buday
2023-09-12 16:18 ` Katherine Cox-Buday
2023-09-09 10:01 ` Simon Tournier
2023-09-09 19:45 ` Ricardo Wurmus
2023-08-28 8:15 ` Giovanni Biscuolo
2023-08-28 17:00 ` Liliana Marie Prikler
2023-08-30 7:37 ` Giovanni Biscuolo
2023-08-29 9:29 ` MSavoritias
2023-08-29 19:29 ` Liliana Marie Prikler
2023-09-08 14:44 ` Ricardo Wurmus
2023-09-08 18:50 ` Liliana Marie Prikler
2023-09-08 20:24 ` Ricardo Wurmus
2023-09-08 23:26 ` Liliana Marie Prikler
2023-09-09 19:40 ` Ricardo Wurmus
2023-09-09 22:20 ` Liliana Marie Prikler
2023-09-11 10:36 ` Simon Tournier
2023-09-11 17:53 ` Liliana Marie Prikler
2023-09-11 18:50 ` Simon Tournier
2023-09-12 14:42 ` Maxim Cournoyer
2023-09-12 16:57 ` Simon Tournier
2023-09-13 15:31 ` to PR or not to PR, is /that/ the question? Giovanni Biscuolo
2023-09-13 22:02 ` Simon Tournier
2023-09-14 6:53 ` Giovanni Biscuolo
2023-09-14 7:30 ` Simon Tournier
2023-09-17 16:20 ` How can we decrease the cognitive overhead for contributors? MSavoritias
2023-09-17 16:35 ` Liliana Marie Prikler
2023-09-18 9:37 ` Simon Tournier
2023-09-18 16:35 ` MSavoritias
2023-09-18 17:13 ` Simon Tournier
2023-09-18 17:39 ` MSavoritias
2023-09-18 19:20 ` Simon Tournier
2023-09-18 20:28 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
2023-09-18 19:47 ` Liliana Marie Prikler
2023-09-17 15:50 ` MSavoritias
2023-08-25 23:48 ` Katherine Cox-Buday
2023-08-27 8:35 ` Josselin Poiret
2023-08-25 23:31 ` Katherine Cox-Buday
2023-08-23 20:48 ` Liliana Marie Prikler
2023-08-25 9:03 ` Attila Lendvai
2023-08-27 3:27 ` Maxim Cournoyer
2023-09-02 22:11 ` Ricardo Wurmus
2023-09-03 1:05 ` Vagrant Cascadian
2023-09-04 8:56 ` Ricardo Wurmus
2023-09-04 15:10 ` Efraim Flashner
2023-09-05 2:18 ` Maxim Cournoyer
2023-09-05 7:21 ` Replacing Mumi+Debbugs? Ricardo Wurmus
2023-09-05 13:12 ` How can we decrease the cognitive overhead for contributors? Csepp
2023-09-05 20:30 ` Wilko Meyer
2023-08-23 22:04 ` Ricardo Wurmus
2023-08-23 22:37 ` Jack Hill
2023-08-24 0:18 ` Csepp
2023-08-25 0:10 ` Ekaitz Zarraga
2023-08-26 0:16 ` Katherine Cox-Buday
2023-08-28 21:46 ` paul
2023-08-26 0:06 ` Katherine Cox-Buday
2023-08-27 3:00 ` Maxim Cournoyer
2023-08-27 8:37 ` Josselin Poiret
2023-08-28 9:44 ` Giovanni Biscuolo
2023-08-27 2:50 ` Maxim Cournoyer
2023-08-29 22:40 ` Csepp
2023-08-30 2:46 ` Maxim Cournoyer
2023-08-28 8:52 ` Simon Tournier
2023-08-24 3:33 ` Ahmed Khanzada via Development of GNU Guix and the GNU System distribution.
2023-08-26 0:25 ` Katherine Cox-Buday
2023-08-24 6:33 ` (
2023-08-26 0:39 ` Katherine Cox-Buday
2023-08-27 3:22 ` Maxim Cournoyer
2023-08-27 7:39 ` 宋文武
2023-08-28 11:42 ` Giovanni Biscuolo
2023-09-01 19:12 ` Imran Iqbal
2023-09-03 17:45 ` Ekaitz Zarraga
2023-09-03 21:05 ` indieterminacy
2023-09-03 21:16 ` Ekaitz Zarraga
2023-09-13 12:20 ` Fannys
2023-09-13 15:42 ` Maxim Cournoyer
2023-09-13 23:13 ` Ekaitz Zarraga
2023-09-17 11:29 ` MSavoritias
2023-09-18 10:09 ` Simon Tournier
2023-09-19 10:33 ` contribute with content in our official help pages? Giovanni Biscuolo
2023-09-19 16:35 ` The elephant in the room and the Guix Bang Giovanni Biscuolo
2023-09-19 20:41 ` Simon Tournier
2023-09-20 20:52 ` Giovanni Biscuolo
2023-09-20 8:21 ` Csepp
2023-09-20 8:45 ` The e(macs)lephant " Nguyễn Gia Phong via Development of GNU Guix and the GNU System distribution.
2023-09-20 9:28 ` MSavoritias
2023-09-20 14:03 ` Ricardo Wurmus
2023-09-20 14:09 ` MSavoritias
2023-09-14 8:24 ` How can we decrease the cognitive overhead for contributors? Ricardo Wurmus
2023-09-18 16:40 ` MSavoritias
2023-09-14 17:49 ` Sarthak Shah
2023-09-15 10:18 ` Simon Tournier
2023-09-13 12:25 ` MSavoritias
2023-09-22 15:14 ` Imran Iqbal
2023-09-22 15:30 ` Katherine Cox-Buday
2023-09-22 16:17 ` Ekaitz Zarraga
2023-09-22 16:35 ` MSavoritias
2023-09-22 17:28 ` Ekaitz Zarraga
2023-09-25 15:13 ` Samuel Christie via Development of GNU Guix and the GNU System distribution. [this message]
2023-10-16 20:18 ` Enabling contribution through documentation Matt
2023-11-06 22:43 ` Samuel Christie via Development of GNU Guix and the GNU System distribution.
2023-11-11 1:14 ` Matt
2023-08-28 6:12 ` How can we decrease the cognitive overhead for contributors? (
2023-08-28 9:14 ` Simon Tournier
2023-08-29 9:53 ` MSavoritias
2023-09-05 7:54 ` Simon Tournier
2023-09-13 12:59 ` MSavoritias
2023-09-14 8:18 ` Ricardo Wurmus
2023-08-26 17:40 ` kiasoc5
2023-08-24 9:06 ` Wilko Meyer
2023-08-25 9:31 ` Attila Lendvai
2023-08-26 17:42 ` kiasoc5
2023-08-26 18:53 ` Liliana Marie Prikler
2023-08-26 21:35 ` Attila Lendvai
2023-08-27 8:26 ` Non-committer comments on patches Andreas Enge
2023-08-28 6:17 ` How can we decrease the cognitive overhead for contributors? (
2023-08-28 10:01 ` Simon Tournier
2023-08-28 9:26 ` Simon Tournier
2023-08-24 18:53 ` Simon Tournier
2023-08-26 1:02 ` Katherine Cox-Buday
2023-08-28 10:17 ` Simon Tournier
2023-08-30 16:11 ` Katherine Cox-Buday
2023-08-30 16:53 ` Andreas Enge
2023-08-30 19:02 ` MSavoritias
2023-09-02 11:16 ` Giovanni Biscuolo
2023-09-02 13:48 ` paul
2023-09-02 19:08 ` Csepp
2023-09-02 20:23 ` wolf
2023-09-02 23:08 ` Csepp
2023-09-04 10:23 ` Attila Lendvai
2023-09-04 12:44 ` brian via Development of GNU Guix and the GNU System distribution.
2023-09-04 14:35 ` Attila Lendvai
2023-09-04 18:13 ` Andreas Enge
2023-09-05 9:58 ` pinoaffe
2023-09-05 14:22 ` brian via Development of GNU Guix and the GNU System distribution.
2023-09-05 15:25 ` Maxim Cournoyer
2023-09-05 13:19 ` Csepp
2023-09-05 15:30 ` Maxim Cournoyer
2023-09-05 19:08 ` Csepp
2023-09-06 12:14 ` Attila Lendvai
2023-09-06 12:56 ` Ekaitz Zarraga
2023-09-06 16:03 ` Maxim Cournoyer
2023-09-04 19:16 ` phil
2023-09-04 18:22 ` Andreas Enge
2023-09-02 16:08 ` Csepp
2023-09-02 18:27 ` Mumi search broken? (was: Re: How can we decrease the cognitive overhead for contributors?) Liliana Marie Prikler
2023-09-03 7:36 ` How can we decrease the cognitive overhead for contributors? Ricardo Wurmus
2023-09-03 8:53 ` paul
2023-09-03 10:31 ` Ricardo Wurmus
2023-09-03 14:53 ` Felix Lechner via Development of GNU Guix and the GNU System distribution.
2023-09-04 9:40 ` Giovanni Biscuolo
2023-09-03 18:18 ` Csepp
2023-09-03 20:32 ` Ricardo Wurmus
2023-09-05 8:43 ` Simon Tournier
2023-09-05 18:04 ` Katherine Cox-Buday
2023-09-05 19:15 ` Katherine Cox-Buday
2023-09-13 13:24 ` MSavoritias
2023-09-05 1:32 ` Maxim Cournoyer
2023-09-05 17:19 ` Katherine Cox-Buday
2023-09-05 14:01 ` Simon Tournier
2023-09-05 18:00 ` Katherine Cox-Buday
2023-09-05 20:39 ` Guix User Survey? Wilko Meyer
2023-09-05 23:55 ` How can we decrease the cognitive overhead for contributors? Simon Tournier
2023-09-06 2:58 ` Katherine Cox-Buday
2023-09-06 9:34 ` Next action, survey? Simon Tournier
2023-09-07 20:39 ` Katherine Cox-Buday
2023-09-08 6:31 ` How can we decrease the cognitive overhead for contributors? (
2023-09-05 22:11 ` wolf
2023-09-05 23:02 ` Simon Tournier
2023-09-13 13:59 ` MSavoritias
2023-08-28 21:41 ` paul
2023-08-29 8:32 ` Giovanni Biscuolo
2023-08-29 9:31 ` Giovanni Biscuolo
2023-08-29 11:28 ` git interfaces (was Re: How can we decrease the cognitive overhead for contributors?) Giovanni Biscuolo
2023-08-29 23:11 ` How can we decrease the cognitive overhead for contributors? Csepp
2023-08-30 8:39 ` Attila Lendvai
2023-08-30 9:33 ` Andreas Enge
2023-08-30 0:22 ` Danny Milosavljevic
2023-08-30 9:41 ` Andreas Enge
2023-08-30 12:33 ` commit message helpers (was Re: How can we decrease the cognitive overhead for contributors?) Giovanni Biscuolo
2023-09-04 13:36 ` How can we decrease the cognitive overhead for contributors? Ricardo Wurmus
2023-09-05 3:25 ` Maxim Cournoyer
2023-09-05 7:48 ` Ricardo Wurmus
2023-09-04 11:09 ` David Larsson
2023-09-04 22:06 ` Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?) Arun Isaac
2023-09-05 8:58 ` Debbugs CLI client (was Re: Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?))) Simon Tournier
2023-09-05 10:37 ` Mumi CLI client (was: How can we decrease the cognitive overhead for contributors?) Giovanni Biscuolo
2023-09-08 16:49 ` Ricardo Wurmus
2023-09-12 14:55 ` Giovanni Biscuolo
2023-09-13 8:52 ` Ricardo Wurmus
2023-09-13 10:26 ` Commenting bug reports via mumi web interface " Giovanni Biscuolo
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87h6niffpl.fsf_-_@sdf.org \
--to=guix-devel@gnu.org \
--cc=ekaitz@elenq.tech \
--cc=email@msavoritias.me \
--cc=shcv@sdf.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).