> -----Original Message----- > From: guix-devel-bounces+mec=stowers....@gnu.org [mailto:guix-devel- > bounces+mec=stowers....@gnu.org] On Behalf Of Craig Barnes > Sent: Thursday, September 10, 2015 5:47 AM > To: guix-devel@gnu.org > Subject: Re: Should we start a Guix users wiki? > > On 08/09/15 15:37, Mark H Weaver wrote: > > l...@gnu.org (Ludovic Courtès) writes: > > > >> Craig Barnes <cjbarne...@gmail.com> 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
