Hi,

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

First of all, thank you for trying to get things fixed.

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

I wish you communicated this particular frustration clearly before it
made you very angry.

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

If you don't want me to review the grammar of the PR, feel free to tell
me. You can ask me to focus specifically on certain aspects of it. I'm
used to reviewing academic papers, so I do it the way I'm used to. I
think this is a miscommunication on our part.

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

It's true that I haven't been able to author much content to devmanual
recently. If you look at the same log though, I'm still one of the few
people who commit to the repo. I at least try to review patches and
commit them with what little time I have.

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

And I can do that for you, if you simply communicate this to me. If you
just want me to do a high level overview of the patch, whether the
information is correct, and fits the section, just tell me. I don't
intend to behave in the way you describe. I'm sorry if I come off that
way to you.

I spend the time to point out those fixes anyway. It's easier for me to
just fix it too. I do it out of my respect to you, so you don't feel
like I'm changing your work arbitrarily.

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

The PRs usually get stalled because I try to get at least one more
developer to ack the changes before I merge. There are PRs that I
approved, and are still waiting for another ack. Outside of that, I'm
willing to change our workflow in a way that's more comfortable for you.

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

--
gokturk