From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.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 4Lr5H4W86mSkBAEAauVa8A:P1 (envelope-from ) for ; Sun, 27 Aug 2023 05:01:25 +0200 Received: from aspmx1.migadu.com ([2001:41d0:306:2d92::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id 4Lr5H4W86mSkBAEAauVa8A (envelope-from ) for ; Sun, 27 Aug 2023 05:01:25 +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 3D21D35577 for ; Sun, 27 Aug 2023 05:01:25 +0200 (CEST) Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=JNHdwjFe; 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=1693105285; 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:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=Spu/Q87So0+oR+oAm5jA6eOzHzbAlaL2ikuFIAHAZfw=; b=CB+NuJFQGs9Ib0sbOqBI9d0utw5ktBl9n+CV6H8N8GEKmWuKd/P1V0i68j7qMScjSN0MvS HMejL+nyyR1cXs6rdkjsetBTmKpOy7sel53g9DSbvfP8dBK4NQAWlOY9DuNX/Z1tGJij4g G9V+0TvuRI02TSZbG4xfKpw8dXXbLyKTqu49f6gmLmGCSIXFQgkhmdL2L1UKhjCusWNog/ 7S6ticxga1f8hJoUeFEI9uvHLpCeCSShA5xTRisGUHVS5n3zREyg7SBs+i1uuMthDY4KA+ nqoD3D1ko2SsyZxe/FNy/KQRnfrBPU8LuYwqjbGVbsWycK9qcUQ22V7CAI/i1w== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=gmail.com header.s=20221208 header.b=JNHdwjFe; 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-Seal: i=1; s=key1; d=yhetil.org; t=1693105285; a=rsa-sha256; cv=none; b=XAsY/TPK/LxGAsCP56v9CTiRetryxeU5Ca4Bs4lxzpvuf6tdY8Uc7pShQ76Tqz2TygLf+I hRuX2LHQOegCc79hvt3Ag6PotdAdBvC/3FJctZDDjT3B5jgkdFHJv1eYiGa+uZbNJ7Bk2R ooiFUKYxt8Hkt2ca7+X0grTCr52KN3oKDIix35hS7gCCahMSLrDSgzICIyFD2ssqpQlciy Z1CLoFNUB05FiuoMKCuMxNNvrEf1j2ZuBftKN8YIND5OksT94dcFnVDf8M7jjQ5lMndjRl PLyN9xrQYF1rzhLpqPxt1CdjETyUNZoo6fq9+6nk+lWmxF+a7VcixoUbCLXfLQ== Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qa614-0003MP-Rc; Sat, 26 Aug 2023 23:00:42 -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 1qa613-0003MG-C4 for guix-devel@gnu.org; Sat, 26 Aug 2023 23:00:41 -0400 Received: from mail-qk1-x730.google.com ([2607:f8b0:4864:20::730]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1qa611-0002in-6p for guix-devel@gnu.org; Sat, 26 Aug 2023 23:00:41 -0400 Received: by mail-qk1-x730.google.com with SMTP id af79cd13be357-76d93cf8e13so141381385a.2 for ; Sat, 26 Aug 2023 20:00:38 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20221208; t=1693105237; x=1693710037; h=mime-version:user-agent:message-id:in-reply-to:date:references :subject:cc:to:from:from:to:cc:subject:date:message-id:reply-to; bh=Spu/Q87So0+oR+oAm5jA6eOzHzbAlaL2ikuFIAHAZfw=; b=JNHdwjFeRrHDxNBXpLA74mr36SgtbkCBRDitzHuXGjEEmILKz/gFUGJ1owRttHHMX3 10QeI6l87VTthjOjTl2zX4lV8weCzO47kyosd2e4U5FsChHQsOdYW16QCsnmEIO9TPWW ccyc5HMJxVG/FMEZM+ItFgGOp0wM73I8T+Zj63vsQLMa8nrZkmoRrd4mCG3zHYlHhFH9 DLKifsDkc/wloGt9ZEeEr5l0ZrgbwQF0Ofz2aI0WmSt70pOIbxDy4m00xztK2VRA5IvW SNl8mSUUewOqUUJAOMQprNPGIidKg/Q8dR4O1OUskAZYy/adfxz29wUV3QeH6jwfL5bt D8dw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20221208; t=1693105237; x=1693710037; h=mime-version:user-agent:message-id:in-reply-to:date:references :subject:cc:to:from:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=Spu/Q87So0+oR+oAm5jA6eOzHzbAlaL2ikuFIAHAZfw=; b=ezqp3HMcEba1kDGo0MMcDCEbZeBjWYSvquUmPs8xiAyKB6pnMD2/K4xPpql45YMGuG JeqJi3dj21jpIvbsIlDm0O2zaJeVx+KOTWrN6TAou1iF8k/ctbmtUf3dK20qPHdTjRqU HhncU2hVBZJyXaxEgAKzgDcH7dx94jrgJlQW7vYFBYTi3bsJSakBEpkRLLjQ76shdQHX 0XrhaFqGw2PeqtwzNWkoVt4lVJqEWFLBxU0VFfiHUTY/TdI9ngFNdJr+hvl+jXylbvHS dZWjMOEEcEwLsQnBHSA1VTrlxFORclTHIjG/xVmYa375zb9teeSwJrpQ28Dd1HwjIl66 GBQw== X-Gm-Message-State: AOJu0YyVV7KbzA2uUORqw4iZztWpOlROs0ErD1wFgZpXmJXTESfGu5js iFfuWCMfHzwb83qJrGpChe4NKx7yyqLxGg== X-Google-Smtp-Source: AGHT+IHYqVOYNOFSBwoUli67kIG8dQ7ra8nAgcI9LRGM9hME/gIjQ5NUddvQ3ELulVDWUmCSON/RNg== X-Received: by 2002:a05:620a:4544:b0:76c:e764:5059 with SMTP id u4-20020a05620a454400b0076ce7645059mr29173640qkp.55.1693105237712; Sat, 26 Aug 2023 20:00:37 -0700 (PDT) Received: from hurd (dsl-155-106.b2b2c.ca. [66.158.155.106]) by smtp.gmail.com with ESMTPSA id oo10-20020a05620a530a00b0076cdb0afbc4sm1492884qkn.118.2023.08.26.20.00.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 26 Aug 2023 20:00:37 -0700 (PDT) From: Maxim Cournoyer To: Katherine Cox-Buday Cc: Csepp , guix-devel@gnu.org Subject: Re: How can we decrease the cognitive overhead for contributors? References: <871qfsayyx.fsf@riseup.net> Date: Sat, 26 Aug 2023 23:00:36 -0400 In-Reply-To: (Katherine Cox-Buday's message of "Fri, 25 Aug 2023 18:06:29 -0600") Message-ID: <875y51jijv.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/28.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain Received-SPF: pass client-ip=2607:f8b0:4864:20::730; envelope-from=maxim.cournoyer@gmail.com; helo=mail-qk1-x730.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, 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=ham 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-Country: US X-Migadu-Flow: FLOW_IN X-Migadu-Scanner: mx2.migadu.com X-Migadu-Spam-Score: -7.65 X-Spam-Score: -7.65 X-Migadu-Queue-Id: 3D21D35577 X-TUID: rkarY5/8JANy Hi, Katherine Cox-Buday writes: [...] >> 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. > > Another great example. I don't write much documentation because of this. Texinfo is mostly just plain text until you learn about a few decorators :-). It gives us the info manuals that I find very nifty (it's like a man page, but with hyperlinks and advanced navigation capabilities!) and used across many GNU projects (e.g. coreutils, Emacs, Bash, GCC, GNU Make, etc.) I see it as a strength more than a weakness for the project. -- Thanks, Maxim