Gentoo Archives: gentoo-dev

From: "Michał Górny" <mgorny@g.o>
To: gentoo-dev <gentoo-dev@l.g.o>
Cc: devmanual <devmanual@g.o>
Subject: [gentoo-dev] The demotivating process of contributing to devmanual
Date: Tue, 15 Oct 2019 20:35:51
1 Hello, everyone.
3 I'd like to highlight a major problem with devmanual. For a basic
4 policy & developer documentation thingie, it's quality is so-so at best.
5 A lot of stuff is missing, lots of things are outdated or even
6 incorrect. Not many people are contributing, and those who try quickly
7 resign.
9 I have been very patient with this. However, my pressure has just risen
10 dangerously, and I think it's time to lay my frustration down on this
11 list. Maybe this will finally change something because my supplications
12 were unsuccessful so far.
14 So a typical case of contributing to devmanual looks like this:
16 1. You put an effort to make a good patch. You submit it and wait.
18 2. Usually, after 2 weeks you get review, with a lot of grammar
19 nitpicks. I get that having nice pretty words is important, so I apply
20 them. If I have also tried to keep a nice history, I end up putting
21 the requested changes in appropriate commits. This usually takes
22 as much time as the original change but sure, worth it.
24 3. If you're unlucky, you're told that you're using the wrong formatting
25 style. For example, you used the style of the preceding section which
26 is wrong. Or tyle style from style document which is apparently also
27 wrong [1]. But don't worry, after having to reformat a major change
28 twice you learn to remember the style acceptable by current devmanual
29 project people.
31 4. You wait again. With some luck, this time less than two weeks. Then
32 you learn you need to do more grammar changes. Possibly to stuff you've
33 already changed before. Fixing already takes more time than starting
34 from scratch.
36 5. Eventually, you discover you can't even properly merge the changes
37 back into your commits because the devmanual developers made you start
38 changing stuff you didn't touch in the first place.
40 Then you look at 'git log' and top your frustration with the fact that
41 person who just made you waste another total of 4 hours to
42 unsuccessfully try to update an important document so that it doesn't
43 list practices we don't do for 10+ years, has not made a single change
44 himself in 2 years!
46 No offense intended. I understand people don't have much time. I can
47 understand that people can't even find time to review stuff and get it
48 merged within less than a month. But if you don't have time yourself,
49 why do you keep behaving like everyone else must have tons of free time
50 to get everything perfect for you?
52 I'm going to be blunt here. If you applied suggested changes yourself
53 instead of writing them for me to do, you'd save a lot of time for us
54 both. Or if you just merged it and fixed it yourself afterwards.
55 Or accepted the fact that everything doesn't have to be perfect,
56 and reasonably correct documentation with imperfect grammar is better
57 than obsolete useless documentation that also has imperfect grammar just
58 because it was written before your time.
60 That's all. I've been meaning to write this multiple times but I've
61 instead decided to cool down and spend another hours just to get
62 the work done. Just so I would have a good document to give our proxied
63 maintainers to read, or so I wouldn't have to explain them why our
64 documentation is wrong about every third thing. This time I'm saying
65 enough.
67 Most of my pull requests were apparently approved, so they might be
68 finally merged some day. The update to mirrors [2] still needs
69 requested changes applied, so if you someone wants to take it over,
70 please do. The PR on upstream licenses [3] is still waiting on the main
71 review.
73 That's all. I guess it's the place where you suggest how we can fix
74 this mess.
77 [1]
78 [2]
79 [3]
81 --
82 Best regards,
83 Michał Górny


File name MIME type
signature.asc application/pgp-signature