guix-devel
[Top][All Lists]
Advanced

[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


reply via email to

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