Re: mentoring for documentation
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.
Reply to: