From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp12.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id eLHDHBb322EQzAAAgWs5BA (envelope-from ) for ; Mon, 10 Jan 2022 10:06:30 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp12.migadu.com with LMTPS id oMFwGRb322Ei0wAAauVa8A (envelope-from ) for ; Mon, 10 Jan 2022 10:06:30 +0100 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 1896A12DAF for ; Mon, 10 Jan 2022 10:06:30 +0100 (CET) Received: from localhost ([::1]:39154 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n6qdJ-00009C-8N for larch@yhetil.org; Mon, 10 Jan 2022 04:06:29 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52468) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6qcJ-00083B-J4 for guix-devel@gnu.org; Mon, 10 Jan 2022 04:05:29 -0500 Received: from [2a00:1450:4864:20::12a] (port=38693 helo=mail-lf1-x12a.google.com) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1n6qc2-0000mh-0H for guix-devel@gnu.org; Mon, 10 Jan 2022 04:05:12 -0500 Received: by mail-lf1-x12a.google.com with SMTP id x6so41813726lfa.5 for ; Mon, 10 Jan 2022 01:05:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=from:to:cc:subject:references:date:in-reply-to:message-id :user-agent:mime-version:content-transfer-encoding; bh=VlCO7bFSelxZoxh7RQYXWbe9TF8SkWbyX2on46QXV+U=; b=SIq2WY+7IM+FYHRMeliAeb2QjS8WCy4V8NBvYZ+tUAHypLubYN7iU55/4rLaZPYrnf 0rMfeWxdutGsnB9Z+TpOy4uu1XpIXmeB9Tz8Llqfe3DZhREscKvU20X4NCSrbwCCfec5 JI0ng8vgrvnDTB+WRAgxc4vRXx8du2/Suuo7NDnTaEjSUXWE9FhU+OLB+eC/rrdFfYWb qb4oZy/AwMuDk6DPqqkS9VVUDmsAnVsspZYw7DNcUzYocStrvfT2CeXiBk5hOVPBU95t qX8ffnzpmpu1rxG8YUNcd8jUIhZdD+gs4NLuIi1QCQ22iwaTAiTHsbSn14U2frSpKeQ/ C4aA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:references:date:in-reply-to :message-id:user-agent:mime-version:content-transfer-encoding; bh=VlCO7bFSelxZoxh7RQYXWbe9TF8SkWbyX2on46QXV+U=; b=FdhK8Zw/uufbhSK6ct7mbBHUojT9qLFER2/aqB405H1o1d2yfDisanxyDjuxAplVXs LIcd2V3Nbcak0sneCiRl7As9u+xEnHKVyWfVR2KfC1OUx97jBz8ClarY57Y/OHbJtPRD ZE2ujVjvTquTpoWoRmR44G4ls9wcvQevet2t6oXEdQl7x1s6NSLqfBLD38/WYIPWDbRc n8p3beSC1bM2eHh6BiH4cfoQjkq11M/gL3JOrkiiOQrO3I6T7DYEExNYitmDzXW+85Ij i53Y93LL0CWsqmKCZi7QWPwJMhBz05ekWH0Vre43VPYma6fmiAwbkN7AtJ4i7XCb3Saa lGOQ== X-Gm-Message-State: AOAM533pKY3fC6yCCXP5g4Zn8kL2SbFs99OdJWTpJhOrOnb2jvDRC7GU HMc3ndpxZWOOzmBGJARO3RU= X-Google-Smtp-Source: ABdhPJzgQ0OjX3tBh519DXKxT7V1CgBfOERifdxtigZYKiGicvqh/qVW/IUvzsdTBlAlU8lk/dsKAw== X-Received: by 2002:a19:c505:: with SMTP id w5mr4907914lfe.518.1641805507144; Mon, 10 Jan 2022 01:05:07 -0800 (PST) Received: from guix-xps13 ([89.113.46.52]) by smtp.gmail.com with ESMTPSA id e26sm882649lfn.159.2022.01.10.01.05.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 10 Jan 2022 01:05:06 -0800 (PST) From: =?utf-8?Q?Andr=C3=A9_A=2E_Gomes?= To: Matt Subject: Re: Guix Documentation Meetup References: <87k0faa27i.fsf@elephly.net> <17e3a8189d5.bf62342823554.2534240434231206600@excalamus.com> <17e40afe906.c104327471465.5782260335382192651@excalamus.com> Date: Mon, 10 Jan 2022 12:05:06 +0300 In-Reply-To: <17e40afe906.c104327471465.5782260335382192651@excalamus.com> (matt@excalamus.com's message of "Sun, 09 Jan 2022 16:12:57 -0500") Message-ID: <8735lwufjx.fsf@gmail.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/27.2 (gnu/linux) MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Host-Lookup-Failed: Reverse DNS lookup failed for 2a00:1450:4864:20::12a (failed) Received-SPF: pass client-ip=2a00:1450:4864:20::12a; envelope-from=andremegafone@gmail.com; helo=mail-lf1-x12a.google.com X-Spam_score_int: -12 X-Spam_score: -1.3 X-Spam_bar: - X-Spam_report: (-1.3 / 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, RDNS_NONE=0.793, 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: , Cc: guix-devel , calcium Errors-To: guix-devel-bounces+larch=yhetil.org@gnu.org Sender: "Guix-devel" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1641805590; 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=VlCO7bFSelxZoxh7RQYXWbe9TF8SkWbyX2on46QXV+U=; b=dBSognxfF2GryhXvRN0Zz568OHcyiomabYE8m3zKrdc8KWN2CczdhAHO1J//pRQFUgOHsl VBa9nviKJBbC1CuYCE47sGdXWjI9B7N/0FCoJFQHGMLKUSJm1txmE1Vf6Q2jBx+kjXOn1E 5hACD1Cy/7mMzTolj/446eQcwx5qH8ZPMv4zKzQn1OJAWyBZ151Mei5IlVC/xfnD26n/xn tCrmiQzVQeem581QXkiQmNTnPZDk1uO4RbOIGYp4yFHFPNtiLHwyQ3SdzVAFfHsb2BnF3U MYGEXJctokXo5Fo2OecUsWBv8vJA4u+HgmppJx+I6H19CmaXm0YBVkZM5G0j5w== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1641805590; a=rsa-sha256; cv=none; b=FAAn0psyTmLFreD7VbFMN2pFgK2JBu2pqy2dBJhCXSp4HKihryWSWWwF0alFovwK2OJs6P jbrTTO+njN6koXSXnUqX5TNUnkIrDrdJzwb5I5J1TXeIV2c9h4kBen7nBfWEBI+493bMp/ b0OckKhhQVjFD0rL8lebEzR2wUvtfwxF2alGEfmxajHccMXsTXKs3NbARkFpuiNL9Zt6Gv ukSPNrt3MWYGOX5ZxGVfn/eSiWs1XZqzjAZBj88FcHJkhq0tLdgEXJ1tbz0eESXVCO5rJg lhXy10r+DqGKXCD+ON1i5QnvoTMiraMXcw/mqj19IiGezmvhq62+31VOXg1phg== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=SIq2WY+7; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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" X-Migadu-Spam-Score: -2.01 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=gmail.com header.s=20210112 header.b=SIq2WY+7; dmarc=fail reason="SPF not aligned (relaxed)" header.from=gmail.com (policy=none); 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" X-Migadu-Queue-Id: 1896A12DAF X-Spam-Score: -2.01 X-Migadu-Scanner: scn1.migadu.com X-TUID: Unmd17w98PKW Matt writes: > > I see that this all seems confusing. > > Thank you for your response and for acknowledging my perspective. > Yes, I find many things about the documentation process confusing. I > can't speak for others, but I get the strong sense that I'm not alone > in that feeling. You're not alone, but honestly I think Guix's efforts are heroic to say the least. How many software has no documentation at all? I always gaze at the quality of Guix's manual. > First, the packaging tutorial is, I believe, a reasonable candidate > for the cookbook. It's ready for feedback toward inclusion, not > direct inclusion. The software being packaged isn't ideal as it > involves concepts which may detract from the main subject of > packaging, like stenography. It's also for a plugin and not standalone > software. Demonstrating the final package requires demonstrating the > parent application which again detracts from the main subject of > packaging. Finally, it's written using active voice which conveys > authority on the topic, authority I don't actually have. This was my > first attempt at packaging. > > Second, the troubleshooting post is not, in my option, suited for the > cookbook. It is, however, a good candidate for a wiki page (similar to > Arch wiki sections on troubleshooting). The last time a wiki was > talked about, it seems, was in 2015. I'll start a thread for that. Please don't misinterpret the following comments. You're doing something valuable for the community by the mere fact of talking about Guix - your writings are valuable! But I don't see how the 1st one could land in a cookbook. Regarding the 2nd and the wiki, as someone (perhaps you) already noted, wikis generally host low quality content. Guix's documentation has a ton of examples, perhaps even too many for an expository kind of text. Yes, I'm not a fan of wiki. Regardless, the efforts of such a wiki should perhaps land outside the scope of Guix (i.e. it should be non-"official"). I'm not connected with Guix with any way - a mere enthusiast and observer. I hope you continue to write great articles like these! -- Andr=C3=A9 A. Gomes "Free Thought, Free World"