Hi, On Thu, 2021-06-24 at 20:42 +0200, Marco Möller wrote: > Hello, > I am willing to help improving the Debian documentation. I feel that > existing descriptions are many times too technical and by this not well > inviting beginners to join the Debian community. I believe that > assisting people seeking help could more target also lower entry level > Linux and Debian users. I am considering to help improving the > documentation in this sense. > > Question #1: Is there any mentoring available for learning how to > technically contribute with ideas or text snippets to the Debian > documentation? > Why am I asking this? I have had some first contact with the versioning > system GIT and would know how to accomplish the basic tasks to place a > pull request. Some 20 years ago I also knew how to code a simple HTML > page with its HTML tags and guess that I should be able to learn how > information has to be prepared for the inclusion in a modern web page. > However, my basic GIT skills and my very basic HTML knowledge not > covering CSS and alike modern techniques, both might not be enough > knowledge for avoiding to disturb the workflow of the fluent > contributors. Receiving some mentoring could help to reduce dissonance. >
So far, I don't know any explicit sub-project to address such "technical training" like mentoring. Contributing member doesn't need to do what they are not familiar. I think you should start where you can start easily. Editing wiki content for consistency is an example. > Question #2: Is there a mentoring in the sense of a quality assurance in > place which could approve my contributed snippets for correctness? > Why am I asking this? Willing to especially help where technical > descriptions could benefit by also presenting some paragraphs targeting > the lower experienced audience, I would try my best to prepare text > snippets written from the point of view of a novice. But of course only > the real experts, what I am not, could decide if these snippets are > still rendering the treated topic correctly. I would imagine that the > discussion of a pull request will serve as the quality assurance, but > maybe Debian has other established channels for this. For wiki, if you mess-up a page which others made, they will tell you. For non-wiki based documentation, they usually have corresponding Debian packages. You can file bug report on then with patch. But except for a few documents I am involved, all active contents are for expert. I really don't want to make them longer and descriptive that will exceed my available time resource. That's why I encourage you to work on Wiki-side. > > Question #3: Is there a group of people working on the consolidation of > the present documentation, and how could I join that group? Which documentation are you talking. > Why am I asking this? Before I could contribute with text snippets I am > still struggling with the documentation being dispersed at different > mayor locations: > https://www.debian.org/doc/ > https://wiki.debian.org/ > Even as a simple user, not about contributing to the project, I never > know where to best search for the really up to date information, and > common search engines usually link me to obsolete pages which are not > clearly marked as obsolete pages. Maybe my efforts to help could first > better serve to consolidate information at one place, or to more clearly > present which class of information is supposed to be found at which > location, or to first help marking better the obsolete documentation. Usually wiki is newer and current. I marked many https://www.debian.org/doc/ contents as obsolete. I didn't feel like erasing others' work. So they are there. Anyway, look at published date. That gives you which is current. This is general rule for any free software information. > Question #4: Is my post here on the debian-doc mailing list the correct > place to get my first three questions addressed to the relevant > community members, or shall I better post this on the debian-www list? I may be wrong here but de-fact channel has been, as I see: BTS or debian-doc list --- listed contents https://www.debian.org/doc/ debian-www list --- listing on the web for w.d.o/doc and https://wiki.debian.org/ > Why am I asking this? Well, this is highly related to question #3, I > still feel a little bit lost in unerringly locating on the various and > disperse and many Debian pages the answer for this question #4.
