From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 9BB60138334 for ; Fri, 18 Oct 2019 04:38:02 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id C5D3DE08C4; Fri, 18 Oct 2019 04:37:57 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 4EAAEE0884 for ; Fri, 18 Oct 2019 04:37:57 +0000 (UTC) Received: from [172.16.0.17] (cpe-72-227-68-175.maine.res.rr.com [72.227.68.175]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: desultory) by smtp.gentoo.org (Postfix) with ESMTPSA id D03B534BFE0 for ; Fri, 18 Oct 2019 04:37:55 +0000 (UTC) Subject: Re: [gentoo-dev] The demotivating process of contributing to devmanual To: gentoo-dev@lists.gentoo.org References: <7db69bdd30aeaf350f9c70c28abf9d890656d55c.camel@gentoo.org> From: desultory Message-ID: Date: Fri, 18 Oct 2019 00:37:06 -0400 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:52.0) Gecko/20100101 Thunderbird/52.8.0 Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org X-Auto-Response-Suppress: DR, RN, NRN, OOF, AutoReply MIME-Version: 1.0 In-Reply-To: <7db69bdd30aeaf350f9c70c28abf9d890656d55c.camel@gentoo.org> Content-Type: text/plain; charset=utf-8 Content-Language: en-US Content-Transfer-Encoding: 8bit X-Archives-Salt: b1ae70aa-789e-4d7c-857f-20646353e29f X-Archives-Hash: 3d932f920619aac27e170a7b190aebd4 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 >