[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: mentoring for documentation


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

> 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: