Problem/Motivation

At times, we need to make changes to the English source of the User Guide. This can be due to:
- Changes in Drupal, such as user interface changes
- Suggestions for how to improve the User Guide
- Bug reports in the User Guide
- Etc.

We are currently translating the User Guide into 6 languages, and have had inquiries into at least 2 more. When the English source changes, the translations also need to change. So, we have a process in place for how to deal with this. Currently, this is the process:
https://www.drupal.org/docs/user_guide_guidelines/pm-guide.html#pm-guide...

However, after several months of using this process, Joe and I have found that the process is very cumbersome to follow, because it currently requires us to make changes to some files in the other language directories, and also to make updates to many issues. As we get more languages going, it will get worse. So, we would like to make a change to the process.

Proposed resolution

Step 1 of the current process (determine the scope) still needs to be done.

But we would like to replace the rest of the process with an email list. The idea would be that the leader(s) of each translation team would subscribe to the email list, and Joe or I (when making a change to the English source that requires a change to the other languages too, would post a message to the email list. Then the individual language teams would take appropriate action. We would not be making any changes to the files in the other language directories, even if they haven't been translated.

We already have an email list that we set up earlier in the User Guide process. It isn't being used currently for anything. We can delete the current subscribers, and reuse this list to notify translation teams. The list is here:
https://groups.google.com/forum/#!forum/d8manual

Remaining tasks

a) Amend the process for translation team updates that is currently here:
https://www.drupal.org/docs/user_guide_guidelines/pm-guide.html#pm-guide...
(in source file guidelines/pm-guide.txt)

The new process would say something like this:

[[pm-guide-updates]]
==== Making updates

From time to time, there will be reasons to make updates to the
project_name. For instance, it may need to be updated if a new version of Drupal
comes out, if readers have reported problems, or if new topics need to be
added.

If the guide has been translated, updates are complicated somewhat, because
translators need to be notified about the update. This section tells how to go
about making updates, ensuring that translations are also updated if needed.

. Determine the scope of the change. Some changes to English-language content,
such as fixing typographical errors or minor punctuation or grammar problems, do
not require that translations be updated. But if a substantive change is made to
the content, or a change is made to the AsciiDoc formatting, translations will
also need to be updated.

. When making a change that requires translations also to be updated, add a
"Translation updates needed" tag to your issue. Also, post a message to
the email list that translation group leaders are subscribed to. Suggested message template:
+
----
I wanted to let you know that on this issue:
[ISSUE-LINK]
we made a change to the English source file(s) [FILE-NAME] :

[DESCRIBE-THE-CHANGE]

Here is the commit for reference:
[URL OF COMMIT]

Suggested actions to respond to this change in each language would be either: 
a) If the file hasn't been translated yet, copy the English source file to your language directory and commit it.
b) If the file has already been translated, open a new issue to revise the translation.
----

b) Also add a note to the steps for setting up a new translation group, which are currently on
https://www.drupal.org/docs/user_guide_guidelines/pm-guide.html#pm-guide...
(in the same guidelines/pm-guide.txt file) to say that the translation team leaders need to subscribe to the new email notification list.

c) Ensure that the current translation team leaders are subscribed to the list, and understand (and agree with) this new policy/procedure. Currently, we have the following languages:
en - subscribed (Joe and Jennifer)
ca - subscribed (Ramon)
de - subscribed (Michael, Joachim)
es - subscribed (Juan)
fa - subscribed (novid)
fr - subscribed (SebCorbin)
hu - subscribed (Balu)
in - subscribed (suryanto)
ja - subscribed (kabetani)
uk - subscribed (Andriy, Andrii)
zh-hans - subscribed (Qiangjun)

CommentFileSizeAuthor
#32 2871873-change-process-32.patch6.04 KBjhodgdon
#32 newstep.png7.63 KBjhodgdon
#32 replacements.png14.63 KBjhodgdon
#32 updates.png86.76 KBjhodgdon
#32 phase.png21.18 KBjhodgdon
#16 2871873.patch5.22 KBjhodgdon
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

jhodgdon created an issue. See original summary.

jhodgdon credited Balu Ertl.

jhodgdon credited SebCorbin.

jhodgdon credited anprok.

jhodgdon credited eojthebrave.

jhodgdon credited juanolalla.

jhodgdon credited jungle.

jhodgdon credited podarok.

jhodgdon credited rvilar.

jhodgdon credited vanessakovalsky.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I am adding Joe, as well as all of the translation team managers, to this issue.

I would like to request that all of you please comment on the proposed procedure. Any thoughts? Will this work OK for you? Any changes we should make?

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer commented

As far as I see, I totally understand how much efforts Jennifer and Joe put into tracking all the changes in our locale-related issues. Thank you again for your caring! Thus I agree with the proposed new workflow, I'm subscribed to the e-mail list and received your last message, so let's see, how it could work in the future.

jungle’s picture

jungle
He/Him
Location Chongqing, China
CreditAttribution: jungle as a volunteer commented

Nice solution, it works for me. I subscribed the email-list before.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Thanks for the feedback! I would love to hear from the Spanish and Catalan User Guide translation groups too, as they are also quite active. And of course the French and Ukranian groups are welcome to comment too.

For this to work, we would also need representatives of the Spanish, Catalan, French, and Ukranian groups to subscribe to the email list.

rvilar’s picture

rvilar
Primary language Catalan
Location Montcada i Reixac, Catalonia
CreditAttribution: rvilar at Ymbra commented

Hi jhodgdon, sorry for my silence. I was quite busy last weeks. I agree that the new proposed workflow is better for the scalability of the solution if there are more languages that are coming to the translation effort.

Thank you very much again for all the effort that you put on this.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Status: Active » Needs review
FileSize
2871873.patch5.22 KB

Great! Since we have agreement from HU, CA, and ZH-HANS group leaders, and all three are subscribed to the email list, I am making a patch for the Guidelines.

Assuming this is adopted, we will also need ES, UK, and FR team leaders to subscribe to the email list.

Here's a patch, which affects several sections of the project management guide page:
a) Setting up a new phase -- added a paragraph saying when setting up for translations, create the email list
b) Setting up a new language for translation -- added a step that says the team leaders need to subscribe to the email list
c) The main change is in the "Making updates" section, which is where the process of notifying translation teams about updates to English is.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Anyone subscribed here... your input is also requested on #2872996: Consider whether translation of Drupal Core should be a requirement for User Guide translation

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I just used drupal.org contact forms to contact the remaining people who have not yet commented here and/or joined the email list.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

UK has replied -- thanks @podarok! Would still like to hear from ES and FR teams.

podarok’s picture

podarok
🇺🇦 he/him/his
Primary language Ukrainian
Location Ukraine
CreditAttribution: podarok at ITCare, FFW, Drupal Ukraine Community for Drupal Ukraine Community commented

Not UK, but UA (Ukraine)
UK is United Kingdom
For Ukrainian language we have UA - country, uk - language code.
Feel the pain )))

Great thread BTW
Thanks a lot for heads up
I'm Ukrainian translation team manager and it would be cool if we automate things a little bit
But mailing list is not that good in terms of being on track. Messages goes to SPAM, emails are overwhelming, so would be awesome to keep status page somewhere through http(s) ))))

For Adding updates to USER guide in English I prefer to have versions, not diffs
Because dealing with a diff is a tough. It is not that clear what part is translated, what no. Also, translators sometimes change a bit translation accordingly to the language specifics or even Community specific policies which makes overall diff thing way more harder to track

Instead would be cool to have like version 1.1 which will generate new tree of sources and translators could review those before publishing

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

Ha! Yes, I meant "uk" the language. :)

So. Interesting comments about the process, thanks! Here are a few notes.

When we make changes to the English source at this point, it is usually a change to a paragraph or two in a topic or two, due to either Drupal changing, or someone reporting something incorrect in the Guide. We use an issue in the "User guide content" component, and the plan (in the patch here) is to add an issue tag "Translation updates needed". The notification via email list would be in addition to that.

If you don't like the email list, you could also follow issues from this project, although of course there is no way to subscribe to the issues for a project by component or tag right now. Or you could make a bookmark in your browser for a search on issues in this project in that component and/or with that tag. And you can also go to the email list page https://groups.google.com/forum/#!forum/d8manual to see what has been done recently.

Regarding versions, we are actually doing that already -- when we make a "release" of the User Guide, we also build the e-books. So, for instance, you can look at
https://www.drupal.org/project/user_guide/releases
and see that we made a release of version 8.x-2.0 on 8 September 2016, and then we made an updated release 8.x-2.1 on 13 March 2017, because there had been a few changes to the English source just before that. I do not think we have made any updates to the English source since then, so we have not made a new release. Some releases may also be made from time to time to get the updates for translated languages built into the e-books (not all releases will be due to changes in the English source, but we should put notes on the release page about what is updated).

Does that help, or do you think we need to make some changes to the proposed process?

SebCorbin’s picture

SebCorbin CreditAttribution: SebCorbin at Makina Corpus commented

Hello,

As a member of the french translation group, I'll subscribe to this D8 manual group, but I won't be the one doing most of the work on it, so I'll try to convince some other people to join it too.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Editing proposed message to the email list slightly as I try it out for the first time for issue #2874565: Better table structure for planning-data-types.txt. Here's the message I sent:
https://groups.google.com/forum/#!topic/d8manual/Jrs0F8XInPw

Also, we still need es, fr, and now de groups to subscribe. I'll add a note to the new "Set up de" issue about that for de, as that language is still in the process of setting up.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Adding a few lines to the suggested email message.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Added a list of languages/subscriptions to the issue summary.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Updating language/subscribers list. Still missing participants from FR and ES.

Also, any feedback from the latest few posts there -- do you think this process is sufficient/working, between the issue tag "Needs translation updates" and the email list? I'm especially interested in hearing from @podarok who commented earlier with some less favorable comments... Any other things we could do to make sure notifications happen? Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Adding Persian to the list and fixing a typo in the suggested message to the email list.

novid’s picture

novid CreditAttribution: novid as a volunteer commented

I subscribed to the list, but at this time i am the only member of Persian (Farsi) language team who can participate in the process. If there are some other people willing to help, i will notify them to subscribe.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Thanks!

juanolalla’s picture

juanolalla CreditAttribution: juanolalla as a volunteer commented

Thanks Jennifer and Joe, you're doing an awesome work. I think this new process makes much more sense.

Subscribed to the list. I've been very disconnected lately due to personal life changes, but I'm taking the lead again and I will ensure that those changes are handled by the Spanish team.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Thanks!

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes
FileSize
phase.png21.18 KB
updates.png86.76 KB
replacements.png14.63 KB
newstep.png7.63 KB
2871873-change-process-32.patch6.04 KB

Here's a new patch... please review. For convenience, I have also made screenshots of the 3 sections of output that are changed on the PM Guide section of the Contributor's Guide. The screenshots were made on my local site, so the theme is different...

Three sections updated:

1) Section on setting up a new phase (new step added at end):

Old: https://www.drupal.org/docs/user_guide_guidelines/pm-guide.html#pm-guide...

New last step added:
Screen shot of setting up for new phase section with patch

2) Section on setting up a new language for translation (addition to the replacements section, and new LI added in middle of main issue template):

Old: https://www.drupal.org/docs/user_guide_guidelines/pm-guide.html#pm-guide...

Replacements section with one additional line
New line added to replacements section

New step added to issue template:
New step added to issue template

3) Section on what to do if there are updates to English that require translations
Old: https://www.drupal.org/docs/user_guide_guidelines/pm-guide.html#pm-guide...
New:
Screen shot of the making updates section

Here's the patch...

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented

Patch #32 downloaded, applies cleanly on 8.x-3.x branch, the two affected files (guidelines/pm-guide.txt and scripts/guidelines.conf) opened in Atom, checked in its AsciiDoc Preview mode.

Balu Ertl’s picture

Balu Ertl
he/him
Primary language Hungarian
Location Budapest 🇪🇺
CreditAttribution: Balu Ertl as a volunteer and at Brainsum commented
Status: Needs review » Reviewed & tested by the community

I forgot to toggle issue status...

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Thanks for reviewing! I will wait to commit this change until @eojthebrave has a chance to take a final look, since it's a project management issue. Does anyone from any of the other translation groups have any further comments on the process -- we've been using this for a while now, is it working OK?

Also, we still need someone from the French team to subscribe to the email list please. @SebCorbin said in #22 that he would but... it hasn't happened yet. Thanks! The email list is here:
https://groups.google.com/forum/#!forum/d8manual

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Issue summary: View changes

Thanks @SebCorbin!

eojthebrave’s picture

eojthebrave
he/him
Primary language English
Location Minneapolis, MN
CreditAttribution: eojthebrave at Drupalize.Me commented

This process looks fine to me as outlined in #32. And, having seen it being used already with the email list it seems reasonable. Granted, I'm not actually responsible for maintaining any translation.

I like this a lot better than having to create a new issue for every language. So big +1 from me.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented
Version: 8.x-2.x-dev » 8.x-3.x-dev
Status: Reviewed & tested by the community » Fixed

Great! I've committed the changes, and will get the new Contributor Guide version up on drupal.org after I get the 8.3.x screenshots done on #2857156: Make a 3.x branch... should be later this week or early next week.

If the process needs adjusting, we can always revisit -- so translation groups, let us know either via an issue or the email list. Thanks everyone!

  • jhodgdon committed 0fc55b6 on 8.x-3.x 
    Issue #2871873 by jhodgdon, Balu Ertl, eojthebrave, SebCorbin,...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.