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 3BBB9138334 for ; Tue, 15 Oct 2019 20:35:51 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 4E77CE0883; Tue, 15 Oct 2019 20:35:47 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (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 F1F90E0876 for ; Tue, 15 Oct 2019 20:35:46 +0000 (UTC) Received: from pomiot (c134-66.icpnet.pl [85.221.134.66]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: mgorny) by smtp.gentoo.org (Postfix) with ESMTPSA id 32E5834BE38; Tue, 15 Oct 2019 20:35:45 +0000 (UTC) Message-ID: <7db69bdd30aeaf350f9c70c28abf9d890656d55c.camel@gentoo.org> Subject: [gentoo-dev] The demotivating process of contributing to devmanual From: =?UTF-8?Q?Micha=C5=82_G=C3=B3rny?= To: gentoo-dev Cc: devmanual Date: Tue, 15 Oct 2019 22:35:40 +0200 Organization: Gentoo Content-Type: multipart/signed; micalg="pgp-sha512"; protocol="application/pgp-signature"; boundary="=-9U8uK3vDXfR6t2EYlFaK" User-Agent: Evolution 3.32.4 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 X-Archives-Salt: bb131991-1eb8-46ee-8f91-8a70346b9839 X-Archives-Hash: 36783ee7dab1ba060d1d0f9f7236d2fd --=-9U8uK3vDXfR6t2EYlFaK Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable 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/c= ontributing/devbook-guide/text.xml [2] https://github.com/gentoo/devmanual.gentoo.org/pull/110 [3] https://github.com/gentoo/devmanual.gentoo.org/pull/109 --=20 Best regards, Micha=C5=82 G=C3=B3rny --=-9U8uK3vDXfR6t2EYlFaK Content-Type: application/pgp-signature; name="signature.asc" Content-Description: This is a digitally signed message part Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- iQGTBAABCgB9FiEEx2qEUJQJjSjMiybFY5ra4jKeJA4FAl2mLZ1fFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldEM3 NkE4NDUwOTQwOThEMjhDQzhCMjZDNTYzOUFEQUUyMzI5RTI0MEUACgkQY5ra4jKe JA6LBwf/YSA8mEZ2Q9KzTnpofO06b/xHdQLsfg/PufM+l9Y+YchNt9oGJCYaRbvC 07HaxyKUXLLm86SiLNBFFk0dn6j5J3RwJH8nl6sIg6OXfRJee5zERFUcP9xC0PGC GQVv+14Lu4OyYoxnlIxZRWn9s9Ily7EkHwocsqFotv0fXbYHRhi6PbSStN/iSPx/ JifzpHvGTmiUDAvqMWkz0WMlTaoDNHvSsbMm9nr6rK3ie84c43rGJslgql7+/2cY 1VjZjyjHJkNZqYSOe4PtTLGiQJHV6ft83Uzc4FI5HDam7gWdP8U4AXL0woyerV+X spq6NZXwGYkb6zEySYOUJsN1YCI9sg== =tMaC -----END PGP SIGNATURE----- --=-9U8uK3vDXfR6t2EYlFaK--