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

[desultory <desultory@gentoo.org>]

On 10/15/19 16:35, Michał Górny wrote:
> 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.
> 
Which neatly ignores the historical reasons for it having ended up in
that state. Developer documentation had previously bee spread rather
more broadly, but services got shut down without all of that
documentation being migrated into the remaining service(s). As a
supposedly omnibus resource, the developer manual has yet to come close
to recovering the breadth of what had been available online and even
when the services were shuffled around it was lagging in currency. In
short, this is not a new problem. Hence the tendency toward rapid
burnout in those even considering fixing it all, let alone maintaining
its currency during the process.

To be explicit, I am in no way claiming that the services in question
needed to be retained forever despite infra having decided to shut them
down. I am just noting that having, at the time, multiple "primary
source" references was part of the setup for things evolving in the
manner in which they did. The moral of the story is not that it was
somehow wrong to shut down services which were overly maintenance
intensive, but that data portability is important to data continuity and
that having enough people willing to maintain documentation over time is
important for the health of a project over time.

> 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.
> 
Just as a general note, frustration on the part of one party does not in
any way necessitate action on the part of another party. Sometimes
frustration is justified. Only rarely is public ranting a better
solution than actually discussing the issues at hand with those
responsible for handling them. Far too often both get neglected in favor
of individuals indulging in their own personal catharsis.

> 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.
> 
So, to be blunt, code review is a pointless exercise because the
reviewer could fix things faster themselves. Broken code is fine,
syntactically and semantically invalid code is fine, it can be fixed
after it has broken users systems and lost their data. It is more
convenient for the coder that way, no pesky worries about correctness.
More code more faster.

Seriously though, documentation needs to be accurate and correct to have
value, otherwise it will at best be useless and at worst misinform
people who need to convince machines, which tend to be rather literal
about doing what they are told, to do what is desired of them. Making
good documentation is typically not a trivially easy task, making
documentation just to have something somewhere that may or may not
convey information clearly is not especially useful.

> 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.
> 
Perhaps I am missing how a harangue on the lists neatly explains the
state of documentation in Gentoo, even more confusingly one that it is
essentially making the claim that review is bad because it
inconveniences people who can't be bothered to properly review their own
contributions. The argument is terrible and its delivery no better.

> 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.
> 
Perhaps, and this may be a wild and crazy idea, but it might be useful
to not demotivate the people who are actually working to ensure that
documentation is consistent, readable, and correct; as opposed to public
pillory for not doing even more work for you. Just an idea, since
getting more work out of them is implicitly the motivating factor here.

> 
> [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
>