[gentoo-dev] The demotivating process of contributing to devmanual

[Michał Górny]

Hello, everyone.

I'd like to highlight a major problem with devmanual.  For a basic
policy & developer documentation thingie, it's quality is so-so at best.
A lot of stuff is missing, lots of things are outdated or even
incorrect.  Not many people are contributing, and those who try quickly
resign.

I have been very patient with this.  However, my pressure has just risen
dangerously, and I think it's time to lay my frustration down on this
list.  Maybe this will finally change something because my supplications
were unsuccessful so far.

So a typical case of contributing to devmanual looks like this:

1. You put an effort to make a good patch.  You submit it and wait.

2. Usually, after 2 weeks you get review, with a lot of grammar
nitpicks.  I get that having nice pretty words is important, so I apply
them.  If I have also tried to keep a nice history, I end up putting
the requested changes in appropriate commits.  This usually takes
as much time as the original change but sure, worth it.

3. If you're unlucky, you're told that you're using the wrong formatting
style.  For example, you used the style of the preceding section which
is wrong.  Or tyle style from style document which is apparently also
wrong [1].  But don't worry, after having to reformat a major change
twice you learn to remember the style acceptable by current devmanual
project people.

4. You wait again.  With some luck, this time less than two weeks.  Then
you learn you need to do more grammar changes.  Possibly to stuff you've
already changed before.  Fixing already takes more time than starting
from scratch.

5. Eventually, you discover you can't even properly merge the changes
back into your commits because the devmanual developers made you start
changing stuff you didn't touch in the first place.

Then you look at 'git log' and top your frustration with the fact that
person who just made you waste another total of 4 hours to
unsuccessfully try to update an important document so that it doesn't
list practices we don't do for 10+ years, has not made a single change
himself in 2 years!

No offense intended.  I understand people don't have much time.  I can
understand that people can't even find time to review stuff and get it
merged within less than a month.  But if you don't have time yourself,
why do you keep behaving like everyone else must have tons of free time
to get everything perfect for you?

I'm going to be blunt here.  If you applied suggested changes yourself
instead of writing them for me to do, you'd save a lot of time for us
both.  Or if you just merged it and fixed it yourself afterwards.
Or accepted the fact that everything doesn't have to be perfect,
and reasonably correct documentation with imperfect grammar is better
than obsolete useless documentation that also has imperfect grammar just
because it was written before your time.

That's all.  I've been meaning to write this multiple times but I've
instead decided to cool down and spend another hours just to get
the work done.  Just so I would have a good document to give our proxied
maintainers to read, or so I wouldn't have to explain them why our
documentation is wrong about every third thing.  This time I'm saying
enough.

Most of my pull requests were apparently approved, so they might be
finally merged some day.  The update to mirrors [2] still needs
requested changes applied, so if you someone wants to take it over,
please do.  The PR on upstream licenses [3] is still waiting on the main
review.

That's all.  I guess it's the place where you suggest how we can fix
this mess.


[1] https://github.com/gentoo/devmanual.gentoo.org/blob/master/appendices/contributing/devbook-guide/text.xml
[2] https://github.com/gentoo/devmanual.gentoo.org/pull/110
[3] https://github.com/gentoo/devmanual.gentoo.org/pull/109

-- 
Best regards,
Michał Górny