git@vger.kernel.org mailing list mirror (one of many)
 help / color / mirror / code / Atom feed
From: "Jean-Noël Avila" <jn.avila@free.fr>
To: git <git@vger.kernel.org>
Subject: Re: [Summit topic] Documentation (translations, FAQ updates, new user-focused, general improvements, etc.)
Date: Fri, 22 Oct 2021 16:20:27 +0200	[thread overview]
Message-ID: <1c9adc5d-21ac-f6c6-8a87-959be5420636@free.fr> (raw)
In-Reply-To: <nycvar.QRO.7.76.6.2110211149000.56@tvgsbejvaqbjf.bet>

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.




  reply	other threads:[~2021-10-22 14:20 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 ` [Summit topic] Documentation (translations, FAQ updates, new user-focused, general improvements, etc.) Johannes Schindelin
2021-10-22 14:20   ` Jean-Noël Avila [this message]
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:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

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

  git send-email \
    --in-reply-to=1c9adc5d-21ac-f6c6-8a87-959be5420636@free.fr \
    --to=jn.avila@free.fr \
    --cc=git@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* 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

	https://80x24.org/mirrors/git.git

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).