Re: Guix wiki

[Ricardo Wurmus <rekado@elephly.net>]

Attila Lendvai <attila@lendvai.name> writes:

> sending a patch to the manual is a way higher threshold than editing a
> wiki, especially when it's someone's first contribution. and some
> random, half-baked copy-paste doesn't belong in the manual, while it
> may be very useful when found in a wiki using the search engine.

This is where we disagree.  I’ve wasted so much time in my life
following outdated or wrong instructions on forums or wikis.  I really
don’t want to see anything half-baked anywhere near this project.  There
are few things that frustrate me more than well-meaning but misleading
advice.

The cookbook can have little vignettes on how to do this or that — a
note on how to debug an error, how to configure a certain tool (if the
way it’s done on Guix is special), etc — there is no need to write
full-blown tutorials, obviously.

> also note that i'm programming since i was a child, 30+ years now. at
> least half of it was part of opensource projects, and yet i had quite
> a learning curve getting to the point of submitting patches with any
> level of confidence (but not yet comfort).
>
> emails + debbugs + emacs + double-spaces + whatnot are all a cultural
> thing, and not necessarily simple for aliens, not at all. if you want,
> i can get into the details.

I keep repeating myself: you don’t need to use debbugs.  We do.  Nor do
you need to use Emacs.  (I do.)  You don’t need to use double spacing,
though someone is going to change it for you when applying your changes.

The requirements to contribute to the cookbook or manual are simple:
write text that is useful, correct, and readable, and have someone turn
it into the expected format for you.  If you’re a repeat contributor
your mentor may likely ask you on your next contributions to make a few
changes by yourself, so the learning curve is personalized.

Before Guix I had never used Debbugs.  I rarely ever contributed
patches.  I had no idea how to send patches via email.  There was a time
when I didn’t know that patches are generated with tools.

No aspiring contributor needs to be fully formed before they are
permitted to contribute.  Get yourself a mentor within the project who
can shepherd your contributions and make sure they find their way into
the right files.  Ping them if your contribution seems to have been
forgotten.

In my opinion, a public list of mentors that you can ask to charge of
your contribution would be worth more than a mere info dumping site.

-- 
Ricardo