Re: Guix Documentation Meetup

[André A . Gomes]

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"