Call for contributions to maintain existing documentation - Salsa makes it is easy! (was: Re: Complete and unified documentation for new maintainers

[Otto Kekäläinen]

Hi!

(cross-posting to mentors as they have most experience on what is
wrong with our current docs)

...

Even if somebody in Debian community has enough time to overhaul everything
and create a new documentation, it will become the situation described
in XKCD meme "standards": xkcd.com/927/ -- we just got yet another document
as a fragment as time goes by.

There is no need to start new duplicate parallel efforts. Simply
contribute to the existing ones.

Anyone can edit the current wiki pages if they want to improve them
(although most people I spoke to don't like using MoinMoin, but that
is another topic). If you would like to improve a man page, most
packages in Debian accept Merge Requests on Salsa to improve the man
pages. For example, git-buildpackage has now 29 accepted merge
requests [1], dh-make 16 [2] and debmake 14 [3]. Contributions to
these tool man pages are reviewed by the tool maintainers and thus
likely end up in man pages that are actually correct. Sending MRs to
the tool maintainers likely also helps them stay motivated to continue
to maintain the tools, and the MR contents helps the maintainers get
insight of the "user point of view".

You can easily also contribute to the Debian Developers Reference,
which has already accepted 26 merge requests [4]. The same goes for
the Guide for Debian Maintainers, which has already accepted 26 MRs as
well [5]. The Debian New Maintainers' Guide is abandoned and
deprecated, it should have a more clear banner stating it. The Debian
FAQ [6] has already accepted 13 MRs (8 of them in the past 6 months),
so nothing should be blocking you from contributing improvements
there. The debian.org website has accepted a whopping 716 MRs [7],
contributing there should be easy and fruitful as there are active
reviewers who will guide/help that the update is as good as possible.
The mentors.debian.net has also very active team and 205 accepted MRs
[8].

I have at least MR in all of the above, so I speak out of experience.
The process is smooth and most recipients give the first review
feedback within a week, and after polishing the submissions are likely
to accept.

I warmly recommend others who have time to engage in long discussions
on debian-devel@ to divert some of that energy into updating some of
the documentation.



[1] https://salsa.debian.org/agx/git-buildpackage/-/merge_requests?scope=all&state=merged
[2] https://salsa.debian.org/debian/dh-make/-/merge_requests?scope=all&state=merged
[3] https://salsa.debian.org/debian/debmake/-/merge_requests?scope=all&state=merged
[4] https://salsa.debian.org/debian/developers-reference/-/merge_requests?scope=all&state=merged
[5] https://salsa.debian.org/debian/debmake-doc/-/merge_requests?scope=all&state=merged
[6] https://salsa.debian.org/ddp-team/debian-faq/-/merge_requests?scope=all&state=merged
[7] https://salsa.debian.org/webmaster-team/webwml/-/merge_requests?scope=all&state=merged
[8] https://salsa.debian.org/mentors.debian.net-team/debexpo/-/merge_requests?scope=all&state=merged

[Ahmad Khalifa]

Post by Otto Kekäläinen
There is no need to start new duplicate parallel efforts. Simply
contribute to the existing ones.

+1, please. Too many docs already :)

Post by Otto Kekäläinen
Anyone can edit the current wiki pages if they want to improve them
(although most people I spoke to don't like using MoinMoin, but that
is another topic). If you would like to improve a man page, most
packages in Debian accept Merge Requests on Salsa to improve the man
pages. For example, git-buildpackage has now 29 accepted merge
requests [1], dh-make 16 [2] and debmake 14 [3]. Contributions to
these tool man pages are reviewed by the tool maintainers and thus
likely end up in man pages that are actually correct. Sending MRs to
the tool maintainers likely also helps them stay motivated to continue
to maintain the tools, and the MR contents helps the maintainers get
insight of the "user point of view".

Understandable of course, but the email slows things down a bit.
MoinMoin doesn't have SSO support, but if anyone's interested in OAuth2
and writes python, it's typically very straightforward:
https://moinmo.in/EasyToDo/implement%20oauth

It would be super nice if connected to Salsa or Gitlab.com account

[Jonathan Dowland]

Post by Ahmad Khalifa
Understandable of course, but the email slows things down a bit.
MoinMoin doesn't have SSO support, but if anyone's interested in OAuth2
https://moinmo.in/EasyToDo/implement%20oauth

I'm *fairly* sure that a more pressing issue is that MoinMoin requires
Python 2, which has been abandoned.

At least the stable and deployed versions: 2.0.0a1 is the first release
from the 2.x branch which is a rewrite for Python 3, released 2024-03-24.