From: "Cook, Malcolm" <MEC@stowers.org>
To: 'Craig Barnes' <cjbarnes18@gmail.com>,
"guix-devel@gnu.org" <guix-devel@gnu.org>
Subject: RE: Should we start a Guix users wiki?
Date: Thu, 10 Sep 2015 15:35:29 +0000 [thread overview]
Message-ID: <8987dbc998334ec49782519cb18ca431@exchsrv2.sgc.loc> (raw)
In-Reply-To: <55F15FB8.1010000@gmail.com>
> -----Original Message-----
> From: guix-devel-bounces+mec=stowers.org@gnu.org [mailto:guix-devel-
> bounces+mec=stowers.org@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:
> > ludo@gnu.org (Ludovic Courtès) writes:
> >
> >> Craig Barnes <cjbarnes18@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
prev parent reply other threads:[~2015-09-10 15:35 UTC|newest]
Thread overview: 8+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-09-07 22:08 Should we start a Guix users wiki? Craig Barnes
2015-09-08 8:01 ` Amirouche Boubekki
2015-09-08 9:54 ` Ludovic Courtès
2015-09-08 12:40 ` Thompson, David
2015-09-08 14:37 ` Mark H Weaver
2015-09-10 10:47 ` Craig Barnes
2015-09-10 13:58 ` Ludovic Courtès
2015-09-10 15:35 ` Cook, Malcolm [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=8987dbc998334ec49782519cb18ca431@exchsrv2.sgc.loc \
--to=mec@stowers.org \
--cc=cjbarnes18@gmail.com \
--cc=guix-devel@gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/guix.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.