From: "André A. Gomes" <andremegafone@gmail.com>
To: Matt <matt@excalamus.com>
Cc: guix-devel <guix-devel@gnu.org>, calcium <calcium@disroot.org>
Subject: Re: Guix Documentation Meetup
Date: Mon, 10 Jan 2022 12:05:06 +0300 [thread overview]
Message-ID: <8735lwufjx.fsf@gmail.com> (raw)
In-Reply-To: <17e40afe906.c104327471465.5782260335382192651@excalamus.com> (matt@excalamus.com's message of "Sun, 09 Jan 2022 16:12:57 -0500")
Matt <matt@excalamus.com> 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é A. Gomes
"Free Thought, Free World"
next prev parent reply other threads:[~2022-01-10 9:06 UTC|newest]
Thread overview: 56+ messages / expand[flat|nested] mbox.gz Atom feed top
[not found] <mailman.34870.1641617883.18145.guix-devel@gnu.org>
2022-01-08 8:42 ` Guix Documentation Meetup calcium
2022-01-08 11:35 ` Ricardo Wurmus
2022-01-08 11:49 ` calcium
2022-01-08 16:24 ` Matt
2022-01-08 18:58 ` Ricardo Wurmus
2022-01-08 19:06 ` Leo Famulari
2022-01-09 21:12 ` Matt
2022-01-10 9:05 ` André A. Gomes [this message]
2022-01-10 13:40 ` Matt
2022-01-10 16:05 ` André A. Gomes
2022-01-11 18:45 ` Matt
2022-01-12 18:41 ` Leo Famulari
2022-01-13 0:04 ` Matt
2022-01-10 15:21 ` Planet of Guix-related posts? zimoun
2022-01-11 13:38 ` Matt
2022-01-12 1:40 ` Matt
2022-01-12 5:17 ` André A. Gomes
2022-01-12 8:30 ` Ricardo Wurmus
2022-01-12 9:23 ` Oliver Propst
2022-01-12 8:36 ` Ricardo Wurmus
2022-01-13 0:22 ` Guix Documentation Meetup Leo Famulari
2022-01-13 13:15 ` ilmu
2022-01-08 13:41 ` Matt
2022-01-08 14:09 ` Julien Lepiller
2022-01-08 14:54 ` Matt
2022-01-08 14:39 ` Josselin Poiret
2022-03-10 17:02 Raghav Gururajan
2022-03-10 17:11 ` Raghav Gururajan
-- strict thread matches above, loose matches on Subject: below --
2022-01-08 4:52 Matt
2022-01-10 9:47 ` Oliver Propst
2022-01-10 13:15 ` Matt
2022-01-11 16:24 ` jgart
2022-01-12 0:59 ` Matt
2022-01-12 1:20 ` jgart
2022-01-12 2:57 ` Matt
2022-01-12 3:10 ` Matt
2021-12-13 13:45 Blake Shaw
2021-12-13 15:55 ` Katherine Cox-Buday
2021-12-13 12:41 Blake Shaw
2021-12-13 12:33 Blake Shaw
2021-12-15 17:37 ` Blake Shaw
2021-12-15 19:12 ` zimoun
2021-12-15 22:37 ` jgart
2021-12-11 1:42 Blake Shaw
2021-12-10 22:40 Blake Shaw
2021-12-10 23:18 ` Ryan Prior
2021-12-11 18:55 ` Katherine Cox-Buday
[not found] ` <87lf0q2m7n.fsf@nonconstructivism.com>
2021-12-13 3:50 ` Katherine Cox-Buday
2021-12-30 21:52 ` adriano
2022-01-06 15:58 ` Katherine Cox-Buday
2021-12-13 8:29 ` zimoun
2021-12-14 16:01 ` Katherine Cox-Buday
2021-12-14 17:38 ` Luis Felipe
2021-12-14 17:52 ` Katherine Cox-Buday
2021-12-21 6:41 ` adriano
2021-12-09 9:28 jgart
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://guix.gnu.org/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8735lwufjx.fsf@gmail.com \
--to=andremegafone@gmail.com \
--cc=calcium@disroot.org \
--cc=guix-devel@gnu.org \
--cc=matt@excalamus.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/guix.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).