From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:403:4789::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id 2Dy6CBfV7GT0kwAAauVa8A:P1 (envelope-from ) for ; Mon, 28 Aug 2023 19:10:47 +0200 Received: from aspmx1.migadu.com ([2001:41d0:403:4789::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id 2Dy6CBfV7GT0kwAAauVa8A (envelope-from ) for ; Mon, 28 Aug 2023 19:10:47 +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 D9F8A58445 for ; Mon, 28 Aug 2023 19:10:46 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b="le/NSRe3"; 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=gmail.com ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1693242647; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=nP132OrTYWqB2Tk29Q4CJT/GvWCavwGyG5NkRbfhBfQ=; b=XSK8l9c89YPpHq1OWZ4ar0d6vuO4UDXjkPel/oBshlR3w1PqCx1QpbYtOE3qJZUG24TeW/ NOS9KxLyMglb8q9lxHl0JjfHNnPd/arNRHgVwS0OYa7W8w7ozeNoafp6YO9a9Jd0o+9vwd yNcxTQDB0qrdFmUoFRCCbaaDKLYI/DCTyBDdRNXIB3uq6ziecZlu12WXjutAUfiD5JEO8Z LhxlE0Grzote7zEeo7ddBOdEA90XkH2NfAJoRJxmI7C7EFLrMoatFk+3Vp3DlS82RJrjxO yoLhe+SdvJZOZKBHmU1KNNEuUX9hGjYflQdQ/ISf2Ywdv31xWGOlwvNlryj39A== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1693242647; a=rsa-sha256; cv=none; b=oDwkl9AHy0/5qvPspJu1p27TrupcN9zc83goF7c1bPvB1ROlawi4Pjc7KE8B7PM1LOvmzH Ortu7D8y2j1ZUAtMk/EmJ/ZoWMW5zfAbBHG4XgCuk7kr1tO1ZtH7oo4JQslQO0p/GAlBXm GjT5WeC9uTGLLT12uDg34PJgsIvbuULNg5yzWvkT4+PD3oDdiGQOCILMgQrz3C6+VuuvJI ByysFGNOkLlKXl6M8UHmKKoaSwOPwAOZ+GarCsnPB2PtEqGMCAk70n3n10m0ntZ55Bfs3W W1bWDqVqmZvfHHnXP9R2VdNNtyw6vpjhQ860oSZa7UqB/FxmkMlGQLUGaknENw== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b="le/NSRe3"; 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=gmail.com Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qafks-0004z4-Vv; Mon, 28 Aug 2023 13:10:23 -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 1qafkr-0004yo-OB for guix-devel@gnu.org; Mon, 28 Aug 2023 13:10:21 -0400 Received: from mail-wm1-x32f.google.com ([2a00:1450:4864:20::32f]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qafkp-00050S-I1 for guix-devel@gnu.org; Mon, 28 Aug 2023 13:10:21 -0400 Received: by mail-wm1-x32f.google.com with SMTP id 5b1f17b1804b1-3fef29ce3e5so11066705e9.0 for ; Mon, 28 Aug 2023 10:10:19 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1693242618; x=1693847418; h=content-transfer-encoding:mime-version:message-id:date:references :in-reply-to:subject:cc:to:from:from:to:cc:subject:date:message-id :reply-to; bh=nP132OrTYWqB2Tk29Q4CJT/GvWCavwGyG5NkRbfhBfQ=; b=le/NSRe3Ql+RWUGwPI3OMXtkzBGTm4YSQ7WdXbAjtbK4tOk0r71kxCunwSP+fus+gv creC5XPWX/rVsEjUE0RzEkgHT5K9MIk5you1rhbAprPHwX4d/se7Y4pdcLTkUzm6Q/As jcbuXG9DyfBI07mvMuXQEQAmoNowC9/b0E82cNk2M4E5maylFcbkllvDNBm4SQ3QNuwJ kyaaQdn+VCXvW2AtQ75FhegDfl5E7vwLSKsWLygp+EQDMFiXrXUDCgUk5qXT2zi+uFCa 1tKWS3N2Bpw4N+RswFUQThXR9MdxeIub1bCn3kZUZgEXkcGI25SaCV74OZDm3dbMH7ov qFXw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1693242618; x=1693847418; h=content-transfer-encoding:mime-version:message-id:date:references :in-reply-to:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=nP132OrTYWqB2Tk29Q4CJT/GvWCavwGyG5NkRbfhBfQ=; b=aOzK0Oacgn+pY8sgm0RiMQYLdeFUPYfFphp9g58HqbjNJBZfHErdLpNKKRgmKNXpVv k7j7Da5/+h++UIt3Uux0BneqaibmiLhsXY33BOnVIulJuFUrNYaSuT7tVMxa8PnhP6YM 7rkWCIPkwnneLupWchpMONapGg5XfV4bK8TyHebPVtmU/5Z8Yp4PAG3NA/f2KH+vl7LI HYN1uDL2sU+xGJU+bjNskIiYYpomBwNFxfU57xgo5kaK6D8Z4c80a3f30FtAqE/zDf+Z Q0FxbPABdYRIL45fskABq/LJK0v617CANZiwt1J9oX+cAcV8978k1uefS7XN+hNiSXPn phJw== X-Gm-Message-State: AOJu0Yzoj8buIFpQfPvN3uxk/qtxUWL+ArlgZcD++NODQtyJaAVHONVs 8LJ8njiG+IjRSpOC4CTE3J+RXv6V6Go= X-Google-Smtp-Source: AGHT+IGVdHUq6A35qy5dYofP61MeLO7ctlQ0dPahqBdTpHtcwMLCcd2KKlsZTwOjCuzEWUDc5aG4GA== X-Received: by 2002:a05:6000:188:b0:317:73e3:cf41 with SMTP id p8-20020a056000018800b0031773e3cf41mr19411061wrx.1.1693242617665; Mon, 28 Aug 2023 10:10:17 -0700 (PDT) Received: from pfiuh07 ([193.48.40.241]) by smtp.gmail.com with ESMTPSA id g5-20020a056000118500b00317b063590fsm11107687wrx.55.2023.08.28.10.10.17 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 28 Aug 2023 10:10:17 -0700 (PDT) From: Simon Tournier To: Csepp , Katherine Cox-Buday Cc: guix-devel@gnu.org Subject: Re: How can we decrease the cognitive overhead for contributors? In-Reply-To: <871qfsayyx.fsf@riseup.net> References: <871qfsayyx.fsf@riseup.net> Date: Mon, 28 Aug 2023 10:52:28 +0200 Message-ID: <87y1hvr1kj.fsf@gmail.com> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Received-SPF: pass client-ip=2a00:1450:4864:20::32f; envelope-from=zimon.toutoune@gmail.com; helo=mail-wm1-x32f.google.com X-Spam_score_int: -5 X-Spam_score: -0.6 X-Spam_bar: / X-Spam_report: (-0.6 / 5.0 requ) BAYES_00=-1.9, DATE_IN_PAST_06_12=1.543, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, FREEMAIL_FROM=0.001, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action 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: , 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: -1.61 X-Spam-Score: -1.61 X-Migadu-Queue-Id: D9F8A58445 X-Migadu-Scanner: mx1.migadu.com X-TUID: oy5EX8GRIIRO Hi, On Thu, 24 Aug 2023 at 02:18, Csepp wrote: > By the way, that's another issue. Using a TeX based document format for > the docs is, uuuh, maybe not the best idea. Info is a pretty okayish > documentation reader, but it's a relatively big barrier to entry > compared to what you need to know to make a small edit to the Arch wiki. > This way mostly just experienced contributors write docs, not the > users who just want to document how they made some weird use case > possible. Similarly as the term =E2=80=9Ccontribution=E2=80=9D is large, I would like= to point that the term =E2=80=9Cdocs=E2=80=9D is pointless here. Are we comparing t= he Archi wiki with printed-quality manual? Somehow, there is a range of documentations and they do not necessary require the same format. Well, moreover, I think that the format is a fake problem. To be explicit, I also dislike the Texi format but the main reason why I do not contribute much to any documentation kind is clearly not the format, instead it is, by far far before, my first main reason is the task appears to me boring and it barely fixes my immediate annoyances. To be precise, I have between 5 and 10 items on my TODO list mentioning =E2=80=9CImprove the documentation for this=E2=80=9D or =E2=80=9CWrite a bl= og post for that=E2=80=9D. It=E2=80=99s stuck not because the Texi format but because writing is hard.= For instance, I could write to my blog using Org-mode format or to one of the Guix blogs using Markdown format. Now, if you speak about Fixing-Typo sort of contribution for the documentation, I am sure that just pointing the section and the typo via any mailing list or via IRC, and the typo will be fixed before the end of the next hour. ;-) Cheers, simon