Attila Lendvai <att...@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