guix-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Guix wiki


From: Matt
Subject: Guix wiki
Date: Sun, 09 Jan 2022 16:14:13 -0500
User-agent: Zoho Mail

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 
<https://lists.gnu.org/archive/cgi-bin/namazu.cgi?idxname=guix-devel>
- search the mailing list at GMane 
<http://dir.gmane.org/gmane.comp.gnu.guix.devel>

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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]