Robert, I appreciate your addition to the discussion.
On Wednesday, December 4, 2024 8:53:07 AM MST Robert Chéramy wrote: > 1) Documentation > There was a lot of reading involved (no problem here - it is great to > have a detailed documentation) but it was very confusing that there were > different guides addressing the same things: In my initial email I didn’t address the topic of documentation, but it is an important aspect that deserves consideration. My personal experience in beginning to contribute to Debian involved me reading over the documentation for a period of three months before beginning to do any work on a package. I found the documentation to be suboptimal for two main reasons. 1. There is currently no canonical packaging workflow in Debian I didn’t even realize how much of a problem this was at the beginning, because I assumed that of course there was only one workflow that was being described to me in the documentation. It is only a slight exaggeration to say that the existing documentation could be summarized as follows: “There are seventeen different ways to create a Debian package. We are only going to consider fifteen of them here. Every one is different. You should just use the one that works best for your situation. We can’t be bothered to explain to you how you can tell which one will be best for your situation, but you will know it when you see it. Also, most of these workflows are incompatible with each other, and everyone who uses any workflow besides the one I like is an idiot. Also, I can’t be bothered to explain all the intermediary steps or any corner cases, but you’ll figure them out as your go.” I have written in other venues about the need for Debian to pick one canonical workflow. This workflow could then be documented in detail, including corner cases, and presented in a step-by-step guide that doesn’t assume any previous knowledge about Debian. There are several people diligently working on trying to get Debian to consolidate on one (or a few) accepted workflows, but the resistance from some developers who have their other favorite workflows is intense. In my personal opinion, for the good of the project and the need to attract far greater than 1,000 active Debian Developers, we need to overcome our personal workflow opinions and consolidate on one choice, even if we consider choice to be technically inferior to our preferred option. 2. A vast amount of the step-by-step documentation written for beginners regarding how to package for the first time is subtly outdated in ways that become very confusing to beginners. Usually, at the time the documentation was written, it was correct. But things change quickly in Debian, and often nobody revisits and updates these howto guides. I think that if we want to get serious about ever attracting a large number of new Debian Developers, we need a team of people (probably, again, a DPL delegation) who has authority and focus to produce the canonical documentation for packaging for beginners. That documentation would need to be constantly updated to be accurate, should be easily discoverable on Debian Mentors, should consist of a single howto document that steps through everything from beginning to end (with references to things like Debian Policy), and should focus on one canonical workflow (meaning that, if we can’t as a project agree on a workflow as described in point 1 above, the new packager documentation should pick one anyway and say, “This is the one true workflow that all new contributors should use to learn how to package for Debian”). It probably goes without saying that both of the points I have made above will be unpopular with certain circles, particularly the link between picking a canonical workflow and making it easier to attract new Debian contributors. But I don’t see anything else that will move the needle. I have been paying fairly close attention to Debian for the past 25 years, and I am not aware of the active Debian Developers ever being much higher than 1,000 people. Despite the discussion about attracting more contributors being a perennial part of almost every DPL platform, we don’t seem to be able to change the status quo. My sense is that to really accomplish what Debian wants to accomplish, we need something more like 10,000 active Debian Developers. If we ever want to get there, we need to so something that goes beyond all the things we have previously tried. And as far as I can tell, having a really good onboarding process that doesn’t depend on having real-life contact with a Debian Developer is something that has never been tried. -- Soren Stoutner so...@debian.org
signature.asc
Description: This is a digitally signed message part.
