From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.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 UCGuJkxQ22EVVgAAgWs5BA (envelope-from ) for ; Sun, 09 Jan 2022 22:14:52 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id wBAaJExQ22EZ+QAA9RJhRA (envelope-from ) for ; Sun, 09 Jan 2022 22:14:52 +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 4B3DD3FA75 for ; Sun, 9 Jan 2022 22:14:52 +0100 (CET) Received: from localhost ([::1]:39556 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1n6fWd-0008IH-Fg for larch@yhetil.org; Sun, 09 Jan 2022 16:14:51 -0500 Received: from eggs.gnu.org ([209.51.188.92]:47044) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6fW6-0008I3-Fp for guix-devel@gnu.org; Sun, 09 Jan 2022 16:14:18 -0500 Received: from sender4-op-o14.zoho.com ([136.143.188.14]:17425) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1n6fW4-0006oj-Ki for guix-devel@gnu.org; Sun, 09 Jan 2022 16:14:18 -0500 ARC-Seal: i=1; a=rsa-sha256; t=1641762853; cv=none; d=zohomail.com; s=zohoarc; b=b4/3IlDWWOTiflYvYFgUcvjeCYuhqbbBZBun10Fvf6oNGNyKLRggLtU4tUqubcqoKVcDyvtNHGezHMV7YkoGmhMSvPQPDdEXMh6ZncZP7V+oeGkLAuLHNcuNRBc5CNjNvMt7kHj8wtFzPzC3OymbtIzHAhBIW5r0FyCKYBGvOEo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1641762853; h=Content-Type:Content-Transfer-Encoding:Date:From:MIME-Version:Message-ID:Subject:To; bh=aBHR2EcrGRYm2PDqVbdhe/T8yNqWcu7PteT9lHX/ISo=; b=RB5xcVyxMwPjQmH8PSeOjDygIplEl7zl5SSdzii3VQaUv+bAKyJ9lpO//B53tsBrstA6UnSproAwqMIulofzcgRxI2wF5nBpGjwGJ7CvZqtc4UqU0dN1xqA4hFuYGAgZo9MmFdUbqzAuxajWvoIBYA4Jh1pyITlDMgQhMMpVBB4= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass header.i=excalamus.com; spf=pass smtp.mailfrom=matt@excalamus.com; dmarc=pass header.from= DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; t=1641762853; s=zmail; d=excalamus.com; i=matt@excalamus.com; h=Date:From:To:Message-ID:Subject:MIME-Version:Content-Type:Content-Transfer-Encoding; bh=aBHR2EcrGRYm2PDqVbdhe/T8yNqWcu7PteT9lHX/ISo=; b=XAoEtpd+LDDULRlVd8TPjmlz1wNj9p8CwXTPEDcYz1+PfRfdRbSyC0dzAkinvh0Q 4sxPPTNEJgzkzkkzhUb9dNHFnbHB/FfiNYPgT8S5zaTx2mjbNwt9CiidFoMlzr4CViq k1RsoVLKRokWdJdg1JfbW1P75jfpJMat/FNX57Ck= Received: from mail.zoho.com by mx.zohomail.com with SMTP id 1641762853362735.215729556472; Sun, 9 Jan 2022 13:14:13 -0800 (PST) Date: Sun, 09 Jan 2022 16:14:13 -0500 From: Matt To: "guix-devel" Message-ID: <17e40b111ce.bc05a4a071499.1598136714226569120@excalamus.com> Subject: Guix wiki MIME-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: 7bit Importance: Medium User-Agent: Zoho Mail X-Mailer: Zoho Mail Received-SPF: pass client-ip=136.143.188.14; envelope-from=matt@excalamus.com; helo=sender4-op-o14.zoho.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.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, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, 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" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1641762892; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type: content-transfer-encoding:content-transfer-encoding:list-id:list-help: list-unsubscribe:list-subscribe:list-post:dkim-signature; bh=aBHR2EcrGRYm2PDqVbdhe/T8yNqWcu7PteT9lHX/ISo=; b=JG7GM2kNvJ58AHUhF1q+icv+IyuCoR3JnrVXbJtCF0jh02dmVVpT50z5TKrBH4W0+3fTKm bUSpdvDZvVpDHGVRikkpU9qoUI9CZk05832nky4VM0i2TmlJZwcaMrzUlnsA15bboxbhi1 v7g+EaNOS7vh0dGwxU/yDLJ9N+w2jHSGZjmoUSZ7kVhd6kc5DW4Gslb/q8HOOXMLXeDwWX xI0oXbaByTNz3nEwhszP9SO9uwGp6cetXwhmlrHIOWls2nzvKoYzMnsZUkKc+Ty0oxCnzz dgfbqbUf88hnZfwvD3uL9uU/DHHc5MheSpbpYqKqSWXw16eMnD6jIiDtBqaHlw== ARC-Seal: i=2; s=key1; d=yhetil.org; t=1641762892; a=rsa-sha256; cv=pass; b=r4UEXdgcp0MjJtICSmHJyaBL2Vp0R1c7r/KxdAitbQaw/xdpF0voWv0infqfPZYw9uDyjv d3OW1ZwRYjqofSbXe/t3SNjoj/GdgCXUZUtnOVfy2c/43vO+j8EkjVhRfSNTDTgAMlvluJ FuO6vWdAD++mRmH0OHpz/ZBEh5ba5e9wP6OnTCMX05+6WILWk3rQ0rg0DlpCkJ5l7eC8Oq nKNbSCBaWrzgbrl6QCA++xLITCEhPKFs63xcHGb16G9f+4hJbpfWgXxnkHtF34rnAEPE+Q teGTFXTQmfbNaKGSquMC1RJsQWp6qT217+HRIuy8TUD7B2zKT2yR/ZM8t/B+9A== ARC-Authentication-Results: i=2; aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=XAoEtpd+; arc=pass ("zohomail.com:s=zohoarc:i=1"); dmarc=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: -4.80 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=excalamus.com header.s=zmail header.b=XAoEtpd+; arc=pass ("zohomail.com:s=zohoarc:i=1"); dmarc=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: 4B3DD3FA75 X-Spam-Score: -4.80 X-Migadu-Scanner: scn1.migadu.com X-TUID: A989PImJtd3l The subject of a wiki came up in the Guix Documentation Meetup thread. The last time it seems a wiki was mentioned was in 2015[fn:1]. Since it's been more than 5 years and the Guix community has grown, I feel it's worth bringing up again. The 2015 post expressed problems with the manual, that it lacks exhaustive examples and that information is hard to find. The following concerns were raised (not listed in the order they appeared): 1. guix will be soon be distributed over gnunet 2. it's hard to know which version of software a wiki is talking about 3. the manual is stored in the same git repository as Guix itself, so they can be kept in sync at all times 4. wikis "tends to be disorganized, unmaintained, and often misleading" 5. having a wiki may confuse what the primary source of documentation is (i.e. the manual) 6. the manual would require far less work from our small pool of experts to maintain than a wiki 7. the manual can easily be read and modified while offline 8. the manual should have all the examples necessary for people to understand how to tweak things Alternatives to the manual were given: - search the mailing list at - search the mailing list at GMane Is that a fair summary? Since both sides weren't examined, I don't think it right to call the thread a discussion. There was no ill-will or bad intent. The concerns are valid and some may still be relevant. There simply didn't seem to be general interest in a wiki. I suspect that interest may have changed. I'm hoping others will join me in having an earnest, goal focused, and respectful conversation about whether Guix should have an official wiki. Why a wiki? Here are some benefits a wiki would provide: 1. lower the barrier of entry for would-be contributors 2. facilitate collaboration 3. allow contributions on the go (from mobile devices) 4. host content not suitable for Texinfo or for inclusion in a reference manual 5. foster community Foremost, I believe a wiki is a good idea because community is central to the GNU philosophy. Guix is at the forefront of the GNU system. It offers something no other system does and, as such, has a unique opportunity to engage people on the ideals of free software. I trust I'm not alone in hoping that the model of Guix package management and reproduciblity, if not Guix itself, becomes the norm for computing. For this to happen, there must be community. Wikis are synonymous with community. Addressing the concerns: Concern 1: guix will be soon be distributed over gnunet I'm not familiar with gnunet. Has this come to fruition? Are the two mutually exclusive? Is it not possible to host the same text using both gnunet and www? If the www wiki would mirror the gnunet wiki, is there something that prevents gnunet mirroring www? Concern 2: it's hard to know which version of software a wiki is talking about I suspect this is still a potential problem. I also suspect Guix itself may help solve it. For example, it's possible to write documentation in such a way that examples use a particular version of Guix using guix time-machine and guix shell. What are examples of this being a problem? Concern 3: the manual is stored in the same git repository as Guix itself, so they can be kept in sync at all times Pushing to the same repo certainly helps make it possible to submit documentation alongside a code change in the same commit. If commits are reviewed, such changes could be enforced as policy. What's the current practice for this? Being in the same repo, however, doesn't necessarily ensure the two are in sync. Unless the documentation is generated from the code itself, I see this more as facilitating documentation discipline. Concern 4: a wiki "tends to be disorganized, unmaintained, and often misleading" This depends on what is meant by "tends to". If read as "often is", there is truth to that. However, I see it being true of documentation in general. The quality of documentation of a community project depends entirely on the community. Is there something about the Guix community that might encourage a wiki to be disorganized, unmaintained, or misleading? How have other communities handled these concerns? Concern 5: having a wiki may confuse what the primary source of documentation is (i.e. the manual) I'm not sure I understand why this is a problem. Of course, confusion should be minimized. But the primary source of documentation should be the one that best helps the user. Ideally, that is the manual. Is there a negative consequence for the primary source not being the manual? For example, how many of you have used the Arch wiki to solve problems for something other than the Arch system? Is that a problem? Concern 6: the manual would require far less work from our small pool of experts to maintain than a wiki This is a great point. People who can maintain the codebase and aren't interested in documentation shouldn't have to maintain a wiki. It's a bad idea to split attention. Has the pool of Guix experts grown since 2015? Also what's meant by maintain? Author or administer? The original author of the 2015 post was "more than happy to help maintain a Guix wiki [and], if needed, would be happy to host it somewhere." There currently exist two unofficial Guix wikis: - https://guix.miraheze.org/wiki/Main_Page - https://github.com/SystemCrafters/wiki-site I would gladly contribute to maintaining the quality of the writing. That makes at least 3 admins and 4 contributors. Concern 7: the manual can easily be read and modified while offline This is another good point. Things shouldn't be tied to the internet. Fortunately, most wikis allow users to download the wiki (apart from tools like wget). Unfortunately, the manual requires users to have a full system install and either commit rights or an extended conversion in order to modify. To quote the Wikipedia on wikis, "All that people require to contribute is a computer [including a mobile device], Internet access, a web browser, and a basic understanding of a simple markup language (e.g. MediaWiki markup language)" Concern 8: the manual should have all the examples necessary for people to understand how to tweak things Agreed. Contributing to documentation also shouldn't be as difficult as it currently is, but here we are. Let's figure it out together. :) * Footnotes [fn:1] https://lists.gnu.org/archive/html/guix-devel/2015-09/msg00182.html