Re: [Summit topic] Documentation (translations, FAQ updates, new user-focused, general improvements, etc.)

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Fri, Oct 22 2021, Jean-Noël Avila wrote:

> I'm sorry that my presence at this meeting could have helped a bit for
> some subtopics.
>
> Le 21/10/2021 à 13:56, Johannes Schindelin a écrit :
>> 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
>
> The effort is still ongoing. Unfortunately, there aren't much outputs
> from it, only the inclusion on git-scm.com.
>
> A proposition was sent for Debian packages.
>
> I'm open for any help in packaging what's already available for whatever
> useful.
>
>
> For some statistics
>
> * there are 23 po files, "pt_BR" fully translated, "fr" half translated,
> "de" one third; most other languages have not really started (the
> portion already translated was made automatically for unmodified strings).
>
> * not all pages are included for translation; most porcelain pages
> available on git-scm.com are included, but for instance, not the config
> parts or the guides. That's already 10,687 source segments and 206,700
> source words, which is a volume similar to "Crime and Punishment" by
> Dostoyevsky. And it really looks like an punishment for most apprentice
> translators willing to start.
>
> In order to lower the barrier to translators, the project is relying on
> weblate: https://hosted.weblate.org/projects/git-manpages/translations/
> while still retaining a "Developer's Certificate of Origin".
>
>
>>
>>     2. Peff: Some translated pages are live on git-scm.com (a github repo with
>>        translations)
>
> For instance, git init manpages is already available in 8 languages.
>
>
>>
>>     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
>
> Asciidoc support is "co-developed" in po4a in parallel with the
> translation: I fix bugs when they are found in the po files.
>
>>     4. Taylor: https://github.com/jnavila/git-manpages-l10n
>
>
> If it looks too personal, it can be moved into the git organization.
>
>
>>
>>  5. Philip Oakley: I see manpages used as reference material instead of
>>     educational documents
>>
>>
>>     12. In stackoverflow you can see how people answer questions, how much less
>>         existing background they assume
>
> Version control is usually already in the culture of most users
> (writers, engineers in other fields have come to use them some 10 years
> ago). What their questions usually boil down to is: how can I use and
> customize git features for my field of expertise. When software editors
> include git support in their applications, it is usually with severed
> functions and users quickly have to get back to plain git when they want
> a little more.
>
> General rules can help start up with a new customization, but at some
> point, the customization is specific to the tool. A library of
> application oriented customizations, help files and FAQs may be of
> interest. Some customizations already exist, sometimes with errors
> (meaning the maintainer of the customization has not fully understood
> how git works) but they are scattered.

I'd very much support this living in-tree just as the po/* directory
already does. I.e. periodically pulled down.

There are many OS's that have something like "apt install
manpages-<lang>", so if we had these available they could be much more
useful to users.

E.g. I see I can "apt install manpages-pt", but if you're a Portuguese
speaker you probably won't chase down some third-party addition of
Portuguese manpages, and even if they're in Debian other package
maintainers might not add them if they're not in the "main" package etc.

What's standing in the way of us treating this in the same way as the
po/* directory, if anything?