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 worri
