1 |
On 10/15/19 16:35, Michał Górny wrote: |
2 |
> Hello, everyone. |
3 |
> |
4 |
> I'd like to highlight a major problem with devmanual. For a basic |
5 |
> policy & developer documentation thingie, it's quality is so-so at best. |
6 |
> A lot of stuff is missing, lots of things are outdated or even |
7 |
> incorrect. Not many people are contributing, and those who try quickly |
8 |
> resign. |
9 |
> |
10 |
Which neatly ignores the historical reasons for it having ended up in |
11 |
that state. Developer documentation had previously bee spread rather |
12 |
more broadly, but services got shut down without all of that |
13 |
documentation being migrated into the remaining service(s). As a |
14 |
supposedly omnibus resource, the developer manual has yet to come close |
15 |
to recovering the breadth of what had been available online and even |
16 |
when the services were shuffled around it was lagging in currency. In |
17 |
short, this is not a new problem. Hence the tendency toward rapid |
18 |
burnout in those even considering fixing it all, let alone maintaining |
19 |
its currency during the process. |
20 |
|
21 |
To be explicit, I am in no way claiming that the services in question |
22 |
needed to be retained forever despite infra having decided to shut them |
23 |
down. I am just noting that having, at the time, multiple "primary |
24 |
source" references was part of the setup for things evolving in the |
25 |
manner in which they did. The moral of the story is not that it was |
26 |
somehow wrong to shut down services which were overly maintenance |
27 |
intensive, but that data portability is important to data continuity and |
28 |
that having enough people willing to maintain documentation over time is |
29 |
important for the health of a project over time. |
30 |
|
31 |
> I have been very patient with this. However, my pressure has just risen |
32 |
> dangerously, and I think it's time to lay my frustration down on this |
33 |
> list. Maybe this will finally change something because my supplications |
34 |
> were unsuccessful so far. |
35 |
> |
36 |
Just as a general note, frustration on the part of one party does not in |
37 |
any way necessitate action on the part of another party. Sometimes |
38 |
frustration is justified. Only rarely is public ranting a better |
39 |
solution than actually discussing the issues at hand with those |
40 |
responsible for handling them. Far too often both get neglected in favor |
41 |
of individuals indulging in their own personal catharsis. |
42 |
|
43 |
> So a typical case of contributing to devmanual looks like this: |
44 |
> |
45 |
> 1. You put an effort to make a good patch. You submit it and wait. |
46 |
> |
47 |
> 2. Usually, after 2 weeks you get review, with a lot of grammar |
48 |
> nitpicks. I get that having nice pretty words is important, so I apply |
49 |
> them. If I have also tried to keep a nice history, I end up putting |
50 |
> the requested changes in appropriate commits. This usually takes |
51 |
> as much time as the original change but sure, worth it. |
52 |
> |
53 |
> 3. If you're unlucky, you're told that you're using the wrong formatting |
54 |
> style. For example, you used the style of the preceding section which |
55 |
> is wrong. Or tyle style from style document which is apparently also |
56 |
> wrong [1]. But don't worry, after having to reformat a major change |
57 |
> twice you learn to remember the style acceptable by current devmanual |
58 |
> project people. |
59 |
> |
60 |
> 4. You wait again. With some luck, this time less than two weeks. Then |
61 |
> you learn you need to do more grammar changes. Possibly to stuff you've |
62 |
> already changed before. Fixing already takes more time than starting |
63 |
> from scratch. |
64 |
> |
65 |
> 5. Eventually, you discover you can't even properly merge the changes |
66 |
> back into your commits because the devmanual developers made you start |
67 |
> changing stuff you didn't touch in the first place. |
68 |
> |
69 |
> Then you look at 'git log' and top your frustration with the fact that |
70 |
> person who just made you waste another total of 4 hours to |
71 |
> unsuccessfully try to update an important document so that it doesn't |
72 |
> list practices we don't do for 10+ years, has not made a single change |
73 |
> himself in 2 years! |
74 |
> |
75 |
> No offense intended. I understand people don't have much time. I can |
76 |
> understand that people can't even find time to review stuff and get it |
77 |
> merged within less than a month. But if you don't have time yourself, |
78 |
> why do you keep behaving like everyone else must have tons of free time |
79 |
> to get everything perfect for you? |
80 |
> |
81 |
> I'm going to be blunt here. If you applied suggested changes yourself |
82 |
> instead of writing them for me to do, you'd save a lot of time for us |
83 |
> both. Or if you just merged it and fixed it yourself afterwards. |
84 |
> Or accepted the fact that everything doesn't have to be perfect, |
85 |
> and reasonably correct documentation with imperfect grammar is better |
86 |
> than obsolete useless documentation that also has imperfect grammar just |
87 |
> because it was written before your time. |
88 |
> |
89 |
So, to be blunt, code review is a pointless exercise because the |
90 |
reviewer could fix things faster themselves. Broken code is fine, |
91 |
syntactically and semantically invalid code is fine, it can be fixed |
92 |
after it has broken users systems and lost their data. It is more |
93 |
convenient for the coder that way, no pesky worries about correctness. |
94 |
More code more faster. |
95 |
|
96 |
Seriously though, documentation needs to be accurate and correct to have |
97 |
value, otherwise it will at best be useless and at worst misinform |
98 |
people who need to convince machines, which tend to be rather literal |
99 |
about doing what they are told, to do what is desired of them. Making |
100 |
good documentation is typically not a trivially easy task, making |
101 |
documentation just to have something somewhere that may or may not |
102 |
convey information clearly is not especially useful. |
103 |
|
104 |
> That's all. I've been meaning to write this multiple times but I've |
105 |
> instead decided to cool down and spend another hours just to get |
106 |
> the work done. Just so I would have a good document to give our proxied |
107 |
> maintainers to read, or so I wouldn't have to explain them why our |
108 |
> documentation is wrong about every third thing. This time I'm saying |
109 |
> enough. |
110 |
> |
111 |
Perhaps I am missing how a harangue on the lists neatly explains the |
112 |
state of documentation in Gentoo, even more confusingly one that it is |
113 |
essentially making the claim that review is bad because it |
114 |
inconveniences people who can't be bothered to properly review their own |
115 |
contributions. The argument is terrible and its delivery no better. |
116 |
|
117 |
> Most of my pull requests were apparently approved, so they might be |
118 |
> finally merged some day. The update to mirrors [2] still needs |
119 |
> requested changes applied, so if you someone wants to take it over, |
120 |
> please do. The PR on upstream licenses [3] is still waiting on the main |
121 |
> review. |
122 |
> |
123 |
> That's all. I guess it's the place where you suggest how we can fix |
124 |
> this mess. |
125 |
> |
126 |
Perhaps, and this may be a wild and crazy idea, but it might be useful |
127 |
to not demotivate the people who are actually working to ensure that |
128 |
documentation is consistent, readable, and correct; as opposed to public |
129 |
pillory for not doing even more work for you. Just an idea, since |
130 |
getting more work out of them is implicitly the motivating factor here. |
131 |
|
132 |
> |
133 |
> [1] https://github.com/gentoo/devmanual.gentoo.org/blob/master/appendices/contributing/devbook-guide/text.xml |
134 |
> [2] https://github.com/gentoo/devmanual.gentoo.org/pull/110 |
135 |
> [3] https://github.com/gentoo/devmanual.gentoo.org/pull/109 |
136 |
> |