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.
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.
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.
Question #3: Is there a group of people working on the consolidation of
the present documentation, and how could I join that group?
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.
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?
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.
Best regards,
Marco.
On Thu, Jun 24, 2021 at 08:42:24PM +0200, Marco Möller wrote:
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.
Tip: The major search engines like Google allow you to filter on a given website. e.g. "site:debian.org BTS" will limit searches of the string
BTS to the debian.org site.
On 24.06.21 22:58, Brian Thompson wrote:
On Thu, Jun 24, 2021 at 08:42:24PM +0200, Marco Möller wrote:
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.
The problems is more about the documentation offered on the Debian web-site than about how to use a search engine. For instance, there is this page:Maybe this information is still up to date. Maybe it was forgotten to be moved to the obsolete documents. How should the new user know this? The common search engines, and also the hierarchy of the Debian web-site suggest you this document and the new
https://www.debian.org/doc/user-manuals
It links i.e. to the "APT User's Guide" and following this link we find the information marked with "Copyright © 1998 Jason Gunthorpe". The trained users are unlikely to have a need to read this document and might not be aware about the status of it.
Hello Marco,
I'm aware of the problems you described.
I'm also trying to improve the documentation I stumble upon.
There is alos IRC at OFTC net and a special #debian-doc cchannel.
I can offer to discuss there first ideas. We can also do it per jtsi.debian.social
Kind regards
Mechtilde
Am 24.06.21 um 20:42 schrieb Marco Möller:
(...)
Marco.
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.
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.
Question #3: Is there a group of people working on the consolidation of
the present documentation, and how could I join that group?
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.
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?
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.
| Sysop: | Keyop |
|---|---|
| Location: | Huddersfield, West Yorkshire, UK |
| Users: | 399 |
| Nodes: | 16 (1 / 15) |
| Uptime: | 104:55:47 |
| Calls: | 8,365 |
| Calls today: | 4 |
| Files: | 13,165 |
| Messages: | 5,898,319 |