• mentoring for documentation

    From =?UTF-8?Q?Marco_M=c3=b6ller?=@21:1/5 to All on Thu Jun 24 20:50:02 2021
    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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Brian Thompson@21:1/5 to All on Thu Jun 24 23:00:01 2021
    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.
    --
    Best regards,

    Brian T

    -----BEGIN PGP SIGNATURE-----

    iQIzBAABCgAdFiEE4esj0Kcrx39kfba+Wun9YmRpYOYFAmDU8fsACgkQWun9YmRp YOahlRAAyQ96hYKL0v+MJ+wgHeydV8NgjZONF+W79AAN5ZVx2XdwbQxw9aNglFXw PdJOLRs07a8GI1/VqdOmdc39Ui5b+/gh5F3L374EfNum/pGQK6JCoYvvu11+mP7I mumjSl6awS0WNjoNGbSRI5Ajk0P0w529VRaDeeHXAjrdPT7COrqBVc3zqusW6spG Dd6yb6x3xoU5TkWb2rBiVrNaXESpupZmQcvCF1Ilji6hOl60Fjt6uyablVJG9WVj cQACeK/BHOCrxT9ZbuiFfiASGz46jtjOX02B0/imokA4CYEhIxAYfIY6Xf3rjusc EjE2ZBxa4mXooNyl85qVCAOnMrQWg452LxW1sZ/q46vXETXpixhYHjWco7lpqvvm C3atN0h2R7CxBPwUuY6aW2+eFR/oR9CGSk/CIfzeeDb7ZZ6SaKpR2vclWb1UeNMz NdTKhGM8ZcMG8H28T8fXYQeU7kdsISt9jMxdU3XMVYlwU/GWwEwsjoxn/uL68QyS Wsu2auF34wecP42MczR8gvcJM6Q90kyg9Nm+bEsNfk1LRsWJClaoFYea8KX9FgtE go0ZIpuwspCW7X6bVJlaw2OkX22FcNakw3tWS0U5twR4kt+yjMZs1nmpRCfvFJUk AOloMkPqq4HI1IIOEPORiqsLn11xiHDbaRkNgh3ynMw2h9gS69U=
    =J20T
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Mechtilde Stehmann@21:1/5 to All on Fri Jun 25 07:30:01 2021
    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:
    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.


    --
    Mechtilde Stehmann
    ## Debian Developer
    ## PGP encryption welcome
    ## F0E3 7F3D C87A 4998 2899 39E7 F287 7BBA 141A AD7F

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?Q?Marco_M=c3=b6ller?=@21:1/5 to Brian Thompson on Fri Jun 25 11:00:01 2021
    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.

    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.


    Thanks for the tip. There is also a tag by which this search engine can
    be restricted to results "not older than" - but this is unfortunately
    not always very effective.

    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:
    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. 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 user landing there has maybe a difficult start into Debian.

    It is not about a specific document to exist SINCE a certain date and
    maybe still being valid and of high value, but it is about its validity
    and value UNTIL a certain date. For comparison, here is a site offering documentation which gets this problem nicely under control: https://docs.julialang.org/
    I suggest to learn from such approach to the benefit of Debian. And I am
    aware that some dissonance could arise if joining an established
    community and asking for changes on the already achieved results from
    former hard efforts. But it might be worth it.

    Well, Mechtilde in her post kindly offered to discuss ideas, and I will
    contact her in order to do so, and to learn from her how to friendly and respectfully join the community.

    Marco.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Michael Kesper@21:1/5 to All on Fri Jun 25 12:10:01 2021
    This is a MIME-formatted message. If you see this text it means that your E-mail software does not support MIME-formatted messages.

    --LkOLsqz1OEYlqoZcDlB5wdtWXxIZNnzhS
    Content-Type: text/plain; charset=utf-8
    Content-Language: de-DE
    Content-Transfer-Encoding: quoted-printable

    Hi Marco,

    Am 25.06.21 um 10:51 schrieb Marco Möller:
    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.

    Yes, I feel you.
    It makes me sad when I have to look up up to date infos for Debian on archwiki or ubuntuusers etc.

    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:
    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.
    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
    user landing there has maybe a difficult start into Debian.

    Yes, outdated/unmaintained documentation is worse than none, imho.
    I think creating and maintaining up to date and beginner-friendly documentation has to become a central mission for the Debian project as a whole.

    I'd like to join any such group, too.

    Best
    Michael


    --LkOLsqz1OEYlqoZcDlB5wdtWXxIZNnzhS--

    -----BEGIN PGP SIGNATURE-----

    iQGzBAEBCgAdFiEEpe7P9ZkJ20fmQgZ+YNFHBMPjLrAFAmDVp90ACgkQYNFHBMPj LrBrXgv/d3E0jQD9f5Y27FL4Ku06nSew5XTH4JQmB0t6XuEk18Z+PSFAByfC/KWl wwyVuhGQ13pqL/JCKZck4iJyTy3rzJO3gcCFSHJp6dMZ7IknrkNR9Wq0IiyXPSDy qL0a9y4jLKwb8ubqWrR18ixXQFgMOy/pb2Xtfi1ZQeS6aJqIQbdmb2xm5ftWkCZc YTh5EQMm/lni5KCjdg3M25ZRCNZllurng4sPr/1fNdWaIrrSoqhF1IT4WPJF2C8m cod09PGG3dJC2+ebKQjEzUgcsuD1hBKc2bV1zQXmvq8zEa1vDVZseX3Ag85S3sF2 rd8uQo9ijvbcE7M+7BhFP5BurKeqzJo7fdTKBRcYpZyybgs7e29RvBXA0KhNYINf ewiE+jPiNf1wga5SDDc8GuyyDypi9ATFN5pIbaKwysvbTqigeTYCnU2fddp6642H WShXNs0Q/o9t4BewItiWSqt0pMeDZGK/960AT8qzfzcwDjl6oHNlhQkRupiatc/g
    nVsmGmwj
    =3BuS
    -----END PGP SIGNATURE-----

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From =?UTF-8?Q?Marco_M=c3=b6ller?=@21:1/5 to Mechtilde Stehmann on Fri Jun 25 12:00:02 2021
    On 25.06.21 07:26, Mechtilde Stehmann wrote:
    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 Mechtilde,
    thanks for the kind invitation! I will contact you soon in the
    #debian-doc channel. I envisage to nicely having time to become a more
    active supporter of the community up from the 7th of July, and
    accordingly plan to then enter that channel regularly.

    Before contributing text snippets and in order to best serve the Debian project, it will be good for me to first learn to which source to best
    offer my input to. Is the Debian documentation team more in favor to
    improve the Wiki, or to see the "The Debian Administrator's Handbook"
    being perfectly up-to-date, or something else? Is there a schedule
    suggesting the focus of current documentation activities?
    And I will be curious to hear opinions about the documentation possibly becoming reorganized towards a clearer visibility of validity, like
    offered by other projects, for instance here: https://docs.julialang.org/ .

    Looking forward to discussing our ideas and possibilities,
    best regards,
    Marco!

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)
  • From Osamu Aoki@21:1/5 to All on Sat Jul 10 14:30:01 2021
    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.

    --- SoupGate-Win32 v1.05
    * Origin: fsxNet Usenet Gateway (21:1/5)