[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Should we start a Guix users wiki?
From: |
Cook, Malcolm |
Subject: |
RE: Should we start a Guix users wiki? |
Date: |
Thu, 10 Sep 2015 15:35:29 +0000 |
> -----Original Message-----
> From: address@hidden [mailto:guix-devel-
> address@hidden On Behalf Of Craig Barnes
> Sent: Thursday, September 10, 2015 5:47 AM
> To: address@hidden
> Subject: Re: Should we start a Guix users wiki?
>
> On 08/09/15 15:37, Mark H Weaver wrote:
> > address@hidden (Ludovic Courtès) writes:
> >
> >> Craig Barnes <address@hidden> skribis:
> >>
> >>> Some time ago I asked on IRC about a guix users wiki. Someone
> >>> suggest that I propose one here (sorry it's taken so long).
> >>>
> >>> I think that a wiki would be a good complement to the manual, which
> >>> while quite complete, lacks exhaustive examples (which would be
> >>> impractical).
> >> I have mixed feelings. There are several issues with a Wiki: one can
> >> hardly know which version of the software it’s talking about (whereas
> >> the installed Info pages of PDFs necessarily match the installed
> >> version), and more importantly, it tends to be disorganized,
> >> unmaintained, and often misleading.
> In order to make sure that examples in the manual aren't broken, wouldn't
> something equivalent to python doctests be necessary to ensure this? I think
> it
> would be worse to have a broken example in the manual than somewhere
> else. If the number of examples grow this could be equally unmaintainable.
> > Agreed. There are a small handful of highly successful wikis, but
> > most of them are as Ludovic describes. Maintaining a good wiki
> > requires a great deal of work by experts to monitor changes, fix
> > things up, and to update the wiki as needed when Guix is updated to
> > avoid giving users outdated advice. I suspect it only makes sense
> > when the scale of the documentation and the number of people involved
> > is at least two, maybe three orders of magnitude greater than the Guix
> project.
> >
> >> I would strongly encourage people to help fix the manual as a first
> >> step. If information that a user deems useful is missing from the
> >> manual, then it’s a bug. I’m willing to make it as simple as
> >> possible to fix the manual. But really, the manual should have all
> >> the examples necessary for people to understand how to tweak things.
> > I agree with Ludovic. The manual would require far less work from our
> > small pool of experts to maintain than a wiki, and has a couple of
> > inherent advantages:
> >
> > * the manual is stored in the same git repository as Guix itself, so
> > they can be kept in sync at all times.
> >
> > * the manual can easily be read and modified while offline.
> >
> >> There might be cases where specific information doesn’t quite fit in
> >> the manual, like, say, instructions for a specific laptop model.
> >> These could go in a wiki.
> >>
> >> Overall, I think it’s fine to have stuff at
> >> <https://libreplanet.org/wiki/Group:Guix/> for instance, but the
> >> manual should clearly remain the primary source of documentation,
> >> without any ambiguity.
> Thank you for your feedback on this, I agree with your points, and that in
> this
> case the manual is the better place for this information.
>
> Going back to my original problem of finding information that isn't currently
> in the manual, it would be great if there where an easier way to search /
> browse the mailing list archives. This would make extracting great examples
> to add to the manual easier. Any suggestions would be appreciated.
>
[Cook, Malcolm]
The mailing list archives are searchable per
http://savannah.gnu.org/mail/?group=guix
But, even better, they are also indexed at gmane, which I find to provide
excellent sweet-spot for providing both search and browse - for example this
discussion: http://thread.gmane.org/gmane.comp.gnu.guix.devel/11294/focus=11305
Plus, for any old-school usenet afficianados, gmane provides access via nntp.
(anyone reading this in emacs gnus via nntp)
This being a GNU oriented project I expect moving this to google groups is a
non-starter. "Feh"s and "harrumph"s all around!
>
> Cheers
>
> Craig