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

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 3938 bytes --]

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


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

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

[Mike Gilbert]

On Tue, Oct 15, 2019 at 4:35 PM Michał Górny <mgorny@gentoo.org> 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.

Maybe you should join the project? Especially if you are making major
contributions.

> Most of my pull requests were apparently approved, so they might be
> finally merged some day.

I believe all devs have push access to that repo, so you could just
push the changes yourself if there are no reasonable objections.

Minor mistakes happen, and can be corrected after the fact.

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 1205 bytes --]

On Tue, 2019-10-15 at 16:47 -0400, Mike Gilbert wrote:
> On Tue, Oct 15, 2019 at 4:35 PM Michał Górny <mgorny@gentoo.org> 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.
> 
> Maybe you should join the project? Especially if you are making major
> contributions.

Are you suggesting that I join the project and start committing without
review, or disregarding review?  I have serious doubts on joining
the project if I am repeatedly proven to be doing things wrong --
whether the issues were serious or not.

> 
> > Most of my pull requests were apparently approved, so they might be
> > finally merged some day.
> 
> I believe all devs have push access to that repo, so you could just
> push the changes yourself if there are no reasonable objections.

I never realized that.

> 
> Minor mistakes happen, and can be corrected after the fact.
> 

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

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

[Alec Warner]

[-- Attachment #1: Type: text/plain, Size: 2287 bytes --]

On Tue, Oct 15, 2019 at 1:59 PM Michał Górny <mgorny@gentoo.org> wrote:

> On Tue, 2019-10-15 at 16:47 -0400, Mike Gilbert wrote:
> > On Tue, Oct 15, 2019 at 4:35 PM Michał Górny <mgorny@gentoo.org> 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.
> >
> > Maybe you should join the project? Especially if you are making major
> > contributions.
>
> Are you suggesting that I join the project and start committing without
> review, or disregarding review?  I have serious doubts on joining
> the project if I am repeatedly proven to be doing things wrong --
> whether the issues were serious or not.
>
> >
> > > Most of my pull requests were apparently approved, so they might be
> > > finally merged some day.
> >
> > I believe all devs have push access to that repo, so you could just
> > push the changes yourself if there are no reasonable objections.
>
> I never realized that.
>
> >
> > Minor mistakes happen, and can be corrected after the fact.
> >
>

One tactic here is to just timebound the reviews. 2 weeks between posting a
PR and getting a review is too long IMHO. Post a PR and say you will merge
it in 72 hours or something. If it's wrong, it can be fixed after the fact
as floppym notes.

If I'm at work and someone has sent me a patch and the patch is good but
there are some minor spelling / grammar fixes they can make I will
basically reply pointing out the problems (so they can fix them) but I also
tell them to merge once the fixes are applied. This means they don't need
to wait for me to "review" the spelling fixes. Obviously there is both
trust (in that I assume they did what I asked) and tooling (we have a tool
where I write comments like "you spelled foobare wrong here, should be
'foobar'" and they have to click "RESOLVE" on each item; you can't submit a
PR with 'unresolved' items open) so there is some pressure to "do the right
thing."

-A


>
> --
> Best regards,
> Michał Górny
>
>

[-- Attachment #2: Type: text/html, Size: 3029 bytes --]

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

[Gokturk Yuksek]

[-- Attachment #1.1: Type: text/plain, Size: 5554 bytes --]

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Mike Gilbert]

On Tue, Oct 15, 2019 at 4:59 PM Michał Górny <mgorny@gentoo.org> wrote:
>
> On Tue, 2019-10-15 at 16:47 -0400, Mike Gilbert wrote:
> > On Tue, Oct 15, 2019 at 4:35 PM Michał Górny <mgorny@gentoo.org> 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.
> >
> > Maybe you should join the project? Especially if you are making major
> > contributions.
>
> Are you suggesting that I join the project and start committing without
> review, or disregarding review?  I have serious doubts on joining
> the project if I am repeatedly proven to be doing things wrong --
> whether the issues were serious or not.

I'm suggesting that if you are unhappy with the current way a project
operates, it is easier to change it if you are a project member.

Also, if you need someone to review something, maybe ping people you
know will give useful feedback. I'm usually happy to do a review if
requested personally.

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

[Ulrich Mueller]

[-- Attachment #1: Type: text/plain, Size: 725 bytes --]

>>>>> On Tue, 15 Oct 2019, Michał Górny wrote:

> On Tue, 2019-10-15 at 16:47 -0400, Mike Gilbert wrote:
>> Maybe you should join the project? Especially if you are making major
>> contributions.

> Are you suggesting that I join the project and start committing
> without review, or disregarding review?  I have serious doubts on
> joining the project if I am repeatedly proven to be doing things wrong
> -- whether the issues were serious or not.

Joining the project won't prevent you from asking for review. :)

And if you don't get any reply after waiting for a few days, simply push
your commits. Mistakes in the documentation don't cause any immediate
breakage, and can be corrected later.

Ulrich

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

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

[desultory]

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
> 

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

[Matt Turner]

On Thu, Oct 17, 2019 at 9:38 PM desultory <desultory@gentoo.org> wrote:
>

Since the thread seemed to have already wrapped up with a positive
resolution, I question why you responded in the way you did.

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

[desultory]

On 10/18/19 01:53, Matt Turner wrote:
> On Thu, Oct 17, 2019 at 9:38 PM desultory <desultory@gentoo.org> wrote:
>>
> 
> Since the thread seemed to have already wrapped up with a positive
> resolution, I question why you responded in the way you did.
> 
> 

To quote the original post:

On 10/15/19 16:35, Michał Górny wrote:
> This time I'm saying enough.

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 512 bytes --]

On Tue, 2019-10-15 at 17:20 -0400, Gokturk Yuksek wrote:
> I wish you communicated this particular frustration clearly before it
> made you very angry.

I'm sorry that I vented off here.  I have explicitly requested in some
of my pull requests that you can apply any wording changes directly but
I guess it was easy to miss.

I'm really glad this is resolved, and that the things started moving
again.  I'd like to thank you for all your hard work on devmanual.

-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]

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

[Gokturk Yuksek]

[-- Attachment #1.1: Type: text/plain, Size: 1157 bytes --]

Hi,

Michał Górny:
> On Tue, 2019-10-15 at 17:20 -0400, Gokturk Yuksek wrote:
>> I wish you communicated this particular frustration clearly before it
>> made you very angry.
> 
> I'm sorry that I vented off here.  I have explicitly requested in some
> of my pull requests that you can apply any wording changes directly but
> I guess it was easy to miss.
> 

Seeing this:
https://github.com/gentoo/devmanual.gentoo.org/pull/104#issuecomment-533978623
I stand corrected. I just assumed it was meant to apply for that
particular PR and not in general.

> I'm really glad this is resolved, and that the things started moving
> again.  I'd like to thank you for all your hard work on devmanual.
> 

I'm glad we reached a compromise too. We may not always see eye to eye
but I'll always respect genuine contribution efforts.

Just so that we're on the same page, for the future PRs I'll take a look
at the overall idea, ask one more dev to ack it (doesn't have to be a
devmanual team member), and do the changes I think are necessary post-merge.

Just let me know if you need any further changes to the workflow.

--
gokturk


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 488 bytes --]

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

[Michał Górny]

[-- Attachment #1: Type: text/plain, Size: 741 bytes --]

On Thu, 2019-10-24 at 12:44 -0400, Gokturk Yuksek wrote:
> > I'm really glad this is resolved, and that the things started moving
> > again.  I'd like to thank you for all your hard work on devmanual.
> > 
> 
> I'm glad we reached a compromise too. We may not always see eye to eye
> but I'll always respect genuine contribution efforts.
> 
> Just so that we're on the same page, for the future PRs I'll take a look
> at the overall idea, ask one more dev to ack it (doesn't have to be a
> devmanual team member), and do the changes I think are necessary post-merge.
> 
> Just let me know if you need any further changes to the workflow.
> 

Thank you, I believe that's all we need.


-- 
Best regards,
Michał Górny


[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 618 bytes --]