From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id GOj2CEJfE2Ur0QAAG6o9tA:P1 (envelope-from ) for ; Wed, 27 Sep 2023 00:46:26 +0200 Received: from aspmx1.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id GOj2CEJfE2Ur0QAAG6o9tA (envelope-from ) for ; Wed, 27 Sep 2023 00:46:26 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 035EE5BC51 for ; Wed, 27 Sep 2023 00:46:26 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=sdf.org header.s=sdf.org header.b=RamN859R; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gnu.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1695768386; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=kFiuVtSr4CUIzbK4RyiMsxa7735m36Auv/Zwev//RUs=; b=lpJ+lZbgcW7ItI+xFV/b/CXhVO1itzbQkErZBG6N7okzkowdC5jADTaTwoQ9naVNA0VmQG YWXSfzytbcZYSj71sRqOcMGeEOGadDMKZQu1SGmzXKHBT7uQbkH/KKAEJg15t/iIDq9Udg aWUIJtTElf9PwpRNINhD0S/gtxGh3bVa+ePEzhY/4BN38sX9qpES4mh+wi2xNbqljnx0tB hued7u7irqmzP2r0apS+DFQsFYNCxfGnvMrIo5AXV68wCW/bPtRIok8eH3JtQEPXRG6pv7 4JxyPVJo40t4vFwsoN0wPvdCTwB5OnR1KfJ2/UDSWp1rEE+S3DbjjH849u0TsA== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=sdf.org header.s=sdf.org header.b=RamN859R; spf=pass (aspmx1.migadu.com: domain of "guix-devel-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-devel-bounces+larch=yhetil.org@gnu.org"; dmarc=pass (policy=none) header.from=gnu.org ARC-Seal: i=1; s=key1; d=yhetil.org; t=1695768386; a=rsa-sha256; cv=none; b=oJ8mK5NlDWDt/WjSFSRNmEFaD25bWjGjio0kMs4sE8Iw/rWx79KGLwRthYLqUXNkU/GB/N 2Ognq2v/obMIuIa1fYvHEfuOjI5gk8Yawvo3pJ6GWR7cMcjNueI/u6XrxH6fvEG/FunxYu hlt1Pn909nBAHChqMkv6Wf+A6bHEkJCb1R61NdpRXvDa3tv5jJLrcgNT8DliajdTye94hx QrsDdCeTLxg9xSYCKT6w0ikVwYT1aN1Yd24UZrvDa5erp/+nq9UGLTYYfOEfZ3knsChTSt FisqSp7L75m090n4aqhYOzStspZB0TC/d5MPB4Sz7WrP4925ncVtIRX2SMRqAA== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qlGon-0001m1-R9; Tue, 26 Sep 2023 18:46:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qknKU-0006Q1-6v for guix-devel@gnu.org; Mon, 25 Sep 2023 11:16:58 -0400 Received: from mx.sdf.org ([205.166.94.24]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qknKR-0006Wi-9C for guix-devel@gnu.org; Mon, 25 Sep 2023 11:16:57 -0400 Received: from localhost (68-74-198-14.lightspeed.rlghnc.sbcglobal.net [68.74.198.14]) (authenticated (0 bits)) by mx.sdf.org (8.16.1/8.14.5) with ESMTPSA id 38PFE2IB024158 (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256 bits) verified NO); Mon, 25 Sep 2023 15:14:07 GMT DKIM-Signature: v=1; a=rsa-sha256; c=simple/simple; d=sdf.org; s=sdf.org; t=1695654848; bh=X0gz+F11ONbjnYCBvXBkHF5FRfTdpDggmRR2xSS527Y=; h=From:To:Cc:Subject:References:Date:In-Reply-To; b=RamN859R/lBMwYOG2Nh4AH5fYsOhmvfv1fveKkLcObjM2Uynf2de65IGdnrbMpRLI dSKI0H2dUAus6m7EZc0LQMNDwQRzgEt2n2MNOFlGd1uEQ/XH8imL8vhvj7amr2KOzw l1JKlfvXVuhs/Ir/icHmvbgS2qKyJ0VFgoyEKXHE= To: Ekaitz Zarraga Cc: MSavoritias , guix-devel@gnu.org Subject: Re: Enabling contribution through documentation References: <87msyhgccg.fsf@disroot.org> <547c097a-d805-9a55-11d9-b0434327f89d@gmail.com> <871qfpjhiz.fsf@gmail.com> <87a5udaq7q.fsf@envs.net> <87il8z9yw8.fsf@xelera.eu> <7364531e-5816-799d-5c71-621892082e48@fannys.me> Date: Mon, 25 Sep 2023 11:13:58 -0400 In-Reply-To: (Ekaitz Zarraga's message of "Fri, 22 Sep 2023 17:28:41 +0000") Message-ID: <87h6niffpl.fsf_-_@sdf.org> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; format=flowed Received-SPF: pass client-ip=205.166.94.24; envelope-from=shcv@sdf.org; helo=mx.sdf.org X-Spam_score_int: -16 X-Spam_score: -1.7 X-Spam_bar: - X-Spam_report: (-1.7 / 5.0 requ) BAYES_00=-1.9, DKIM_INVALID=0.1, DKIM_SIGNED=0.1, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-Mailman-Approved-At: Tue, 26 Sep 2023 18:46:02 -0400 X-BeenThere: guix-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Reply-to: Samuel Christie From: Samuel Christie via "Development of GNU Guix and the GNU System distribution." Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: guix-devel-bounces+larch=yhetil.org@gnu.org X-Migadu-Flow: FLOW_IN X-Migadu-Country: US X-Migadu-Spam-Score: -5.70 X-Migadu-Scanner: mx2.migadu.com X-Migadu-Queue-Id: 035EE5BC51 X-Spam-Score: -5.70 X-TUID: vw+Zer+xk5X/ 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