Hi,
On 04/12/2024 15:18, Soren Stoutner wrote:
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.
I could elaborate something to join the discussion properly, but a talk
was given during the last DebConf by Charles and I about the challenges
we identified in attracting and retaining contributors in Brazil, it is
available here:
https://debconf24.debconf.org/talks/74-attracting-and-retaining-new-contributors-insights-from-brazil/
There was some follow-up discussion in Hacker News after a LWN post
about this talk was published:
https://lwn.net/Articles/987548/
https://news.ycombinator.com/item?id=41599327
I think people interested on the subject can get some insights from the
above (comments from people not involved in the project; yes, we, people
already involved in the project, can be very biased). Also ignore some
stupid comments, expected in those public discussions.
And yes, this is something that Debian as whole needs to do better.
--
Lucas Kanashiro
