mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: Johannes Schindelin <>
Subject: [Summit topic] Documentation (translations, FAQ updates, new user-focused, general improvements, etc.)
Date: Thu, 21 Oct 2021 13:56:43 +0200 (CEST)	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

[-- Attachment #1: Type: text/plain, Size: 5968 bytes --]

This session was led by brian m. carlson. Supporting cast: Jeff "Peff"
King, Ævar Arnfjörð Bjarmason, Taylor Blau, Philip Oakley, Emily Shaffer,
CB Bailey, and Jonathan "jrnieder" Nieder.


 1. Background: answering on StackOverflow, other avenues for user questions,
    even users from very large companies

 2. How can we improve documentation?

 3. Maybe even think about translating docs such as FAQs

 4. Peff: there’s an effort to translate manpages

    1. brian: Saw an announcement, haven’t seen what came of it

    2. Peff: Some translated pages are live on (a github repo with

    3. Ævar: It uses a third-party tool (po4a) that uses gettext by making each
       paragraph a translated string. So it’s the same workflow as translating
       code changes

    4. Taylor:

 5. Philip Oakley: I see manpages used as reference material instead of
    educational documents

    1.  Audience often already knows what they’re looking up

    2.  That approach makes it harder to bring people in. Examples are of the
        difficult things instead of how to get started, workable examples that
        can be copy/pasted straight into the shell and tell you how things go

    3.  Emily: We have the two-part Git tutorial (“git help tutorial”) which is
        part of manpages, but I think it’s pretty dated. It starts with how to
        convert your zipfile-based software distribution to Git which is not
        where most people start these days

    4.  Philip: user manual also is not accessible as part of manual

    5.  CB: I wonder if this is even where people look. A lot of new users will
        hit Google and find which historically has been a very
        good introduction

    6.  Slightly misleading calling it Pro Git because it has good

    7.  Philip: maybe the Git project wants to state: we don’t make great
        documentation, look elsewhere

    8.  jrnieder: thank you for the perspective. It’s not quite the intent,
        though, we might just not do a good enough job. For example, when
        examples are too complex, that’s worth improving

    9.  Used to have active contributors who maintained documentation better
        (e.g., Jon Loeliger)

    10. A part of the problem is the format. Pro Git can include diagrams, the
        Git user manual can’t (or at least doesn’t)

    11. brian: likes Pro Git, but maybe not the best for new folks (it assumes
        some familiarity with source code management)

    12. In stackoverflow you can see how people answer questions, how much less
        existing background they assume

    13. Ævar: One issue with the Pro Git book is that it is not under a free
        software license (though it is free of charge). That means it can’t be
        included in free software distributions.

    14. I want to close the gap between output we emit and providing backlinks
        to relevant documentation. E.g. sometimes when we emit advice output,
        we say what config variable is involved and sometimes we don’t

    15. Having documentation distributed with Git is also helpful for having
        something that’s up to date and matches the code people are using

    16. Philip Oakley: Google Season of Docs is a place we can help

    17. brian: Mining stackoverflow has been very helpful for FAQs, helps avoid
        having to give the same answer again and again

    18. Goal is to have a good FAQ in git/git, to be able to link to from

    19. Perl approach of including references in error messages is very useful
        for people being able to solve their own problems

    20. Ævar: “git help git” landing page is not so helpful. I’d prefer
        something like the perl manpage that gives an overview and table of
        contents and nothing else, instead of incorporating reference
        documentation about common options

    21. brian: I’d like to see both in the toplevel manpage. “How to invoke
        git” is something people expect to see when they run “man git”

    22. Ævar: agreed about synopsis, as long as it focuses on the commonly used

    23. Peff: every time I want to look up perl commandline options, I run “man
        perl”, get annoyed, and then run “man perlrun”. I think “man git” does
        the things you’re describing but organized poorly. Even “git help”
        output does a better job of organizing. I also wouldn’t be sad to see
        the options section coming after.

    24. CB: dashed commands should not be listed

 6. Emily: Side topic: the state of git help on stackoverflow is abysmal

    1. Doesn’t have much Git project presence, devrel teams focus on
       company-specific things instead of Git basics.

    2. A lot of answers are just wrong

    3. Someone spending some 20% time on that could improve things a lot and in
       the process would see where people are struggling, which can help us
       make Git more intuitive and make better intuitive tutorial documentation

    4. Ævar: Having a commonly cited FAQ used in stackoverflow can be great

 7. Philip: there are commands that are (at least almost) undocumented, e.g.
    git rerere

    1. brian: Have seen occasions where people struggled with commands like

    2. Ævar: have seen undocumented patches

    3. Tried to improve documentation e.g. git fetch --prune, sometimes
       phrasing is too concise to be helpful

    4. Emily: getting confused e.g. when notes are transported via operations
       such as rebase

    5. Philip: may go in hand with the lack of good examples

 8. Lots of good ideas for contributions!

  parent reply	other threads:[~2021-10-21 11:56 UTC|newest]

Thread overview: 58+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-10-21 11:55 Notes from the Git Contributors' Summit 2021, virtual, Oct 19/20 Johannes Schindelin
2021-10-21 11:55 ` [Summit topic] Crazy (and not so crazy) ideas Johannes Schindelin
2021-10-21 12:30   ` Son Luong Ngoc
2021-10-26 20:14   ` scripting speedups [was: [Summit topic] Crazy (and not so crazy) ideas] Eric Wong
2021-10-30 19:58     ` Ævar Arnfjörð Bjarmason
2021-11-03  9:24       ` test suite speedups via some not-so-crazy ideas (was: scripting speedups[...]) Ævar Arnfjörð Bjarmason
2021-11-03 22:12         ` test suite speedups via some not-so-crazy ideas Junio C Hamano
2021-11-02 13:52     ` scripting speedups [was: [Summit topic] Crazy (and not so crazy) ideas] Johannes Schindelin
2021-10-21 11:55 ` [Summit topic] SHA-256 Updates Johannes Schindelin
2021-10-21 11:56 ` [Summit topic] Server-side merge/rebase: needs and wants? Johannes Schindelin
2021-10-22  3:06   ` Bagas Sanjaya
2021-10-22 10:01     ` Johannes Schindelin
2021-10-23 20:52       ` Ævar Arnfjörð Bjarmason
2021-11-08 18:21   ` Taylor Blau
2021-11-09  2:15     ` Ævar Arnfjörð Bjarmason
2021-11-30 10:06       ` Christian Couder
2021-10-21 11:56 ` [Summit topic] Submodules and how to make them worth using Johannes Schindelin
2021-10-21 11:56 ` [Summit topic] Sparse checkout behavior and plans Johannes Schindelin
2021-10-21 11:56 ` [Summit topic] The state of getting a reftable backend working in git.git Johannes Schindelin
2021-10-25 19:00   ` Han-Wen Nienhuys
2021-10-25 22:09     ` Ævar Arnfjörð Bjarmason
2021-10-26  8:12       ` Han-Wen Nienhuys
2021-10-28 14:17         ` Philip Oakley
2021-10-26 15:51       ` Philip Oakley
2021-10-21 11:56 ` Johannes Schindelin [this message]
2021-10-22 14:20   ` [Summit topic] Documentation (translations, FAQ updates, new user-focused, general improvements, etc.) Jean-Noël Avila
2021-10-22 14:31     ` Ævar Arnfjörð Bjarmason
2021-10-27  7:02       ` Jean-Noël Avila
2021-10-27  8:50       ` Jeff King
2021-10-21 11:56 ` [Summit topic] Increasing diversity & inclusion (transition to `main`, etc) Johannes Schindelin
2021-10-21 12:55   ` Son Luong Ngoc
2021-10-22 10:02     ` vale check, was " Johannes Schindelin
2021-10-22 10:03       ` Johannes Schindelin
2021-10-21 11:57 ` [Summit topic] Improving Git UX Johannes Schindelin
2021-10-21 16:45   ` changing the experimental 'git switch' (was: [Summit topic] Improving Git UX) Ævar Arnfjörð Bjarmason
2021-10-21 23:03     ` changing the experimental 'git switch' Junio C Hamano
2021-10-22  3:33     ` changing the experimental 'git switch' (was: [Summit topic] Improving Git UX) Bagas Sanjaya
2021-10-22 14:04     ` martin
2021-10-22 14:24       ` Ævar Arnfjörð Bjarmason
2021-10-22 15:30         ` martin
2021-10-23  8:27           ` changing the experimental 'git switch' Sergey Organov
2021-10-22 21:54         ` Sergey Organov
2021-10-24  6:54       ` changing the experimental 'git switch' (was: [Summit topic] Improving Git UX) Martin
2021-10-24 20:27         ` changing the experimental 'git switch' Junio C Hamano
2021-10-25 12:48           ` Ævar Arnfjörð Bjarmason
2021-10-25 17:06             ` Junio C Hamano
2021-10-25 16:44     ` Sergey Organov
2021-10-25 22:23       ` Ævar Arnfjörð Bjarmason
2021-10-27 18:54         ` Sergey Organov
2021-10-21 11:57 ` [Summit topic] Improving reviewer quality of life (patchwork, subsystem lists?, etc) Johannes Schindelin
2021-10-21 13:41   ` Konstantin Ryabitsev
2021-10-22 22:06     ` Ævar Arnfjörð Bjarmason
2021-10-22  8:02 ` Missing notes, was Re: Notes from the Git Contributors' Summit 2021, virtual, Oct 19/20 Johannes Schindelin
2021-10-22  8:22   ` Johannes Schindelin
2021-10-22  8:30     ` Johannes Schindelin
2021-10-22  9:07       ` Johannes Schindelin
2021-10-22  9:44 ` Let's have public Git chalk talks, " Johannes Schindelin
2021-10-25 12:58   ` Ævar Arnfjörð Bjarmason

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

  List information:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).