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. Notes: 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 git-scm.com (a github repo with translations) 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: https://github.com/jnavila/git-manpages-l10n 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 git-scm.com/book which historically has been a very good introduction 6. Slightly misleading calling it Pro Git because it has good introductions 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 StackOverflow 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 options 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 this 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!