Merge pull request #93 from chrisdavidmills/add-sync-info

adding section about content sync

1 files changed, 36 insertions, 0 deletions

diff --git a/README.md b/README.md
index 2d947e4af3..9e71968eda 100644
--- a/README.md
+++ b/README.md
@@ -171,3 +171,39 @@ If you want to find out more about our community maintenance teams, see
 [localizing MDN](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Localize).
 If you want to ask questions or talk to us about forming a new community
 maintenance team, see [ask for help](https://developer.mozilla.org/en-US/docs/MDN/Contribute/Getting_started#step_4_ask_for_help).
+
+## Synchronization with the en-US document structure
+
+Before unfreezing the Tier 1 locales, we made an update to synchronize all the
+localized document tree structures with the `en-US` tree structure (English
+slugs only), to make the documentation easier to manage. This resulted in two
+new buckets of documents being created for each locale, existing as
+subdirectories of each local folder:
+
+- `orphaned` — documents that are not associated with any parent `en-US` page.
+- `conflicting` — documents with duplicate translations in existence (e.g.
+  localized once under the existing `en-US` slug, and then again under a
+  localized slug). The duplicate(s) are put in this folder.
+
+Active locale maintenance teams are invited to spend some time exploring the
+orphaned and conflicting documents, to see whether any of this work is worth
+keeping (either adding to, or merging with an existing document in, the main
+tree), or whether it can just be deleted.
+
+### Periodic synchronization updates
+
+We run a GitHub action every day to update the localized documentation and keep
+it in sync with the `en-US` tree structure, for example if documents are deleted
+for, or moved to a different location, in the tree.
+
+When a synchronization occurs:
+
+- Tier 1 (active) locale maintenance teams are given two weeks to decide what to
+  do with the affected documents in their locales to keep things in sync.
+- Tier 2 (frozen) locales have the affected documents deleted/moved immediately.
+
+Note: Conflicting docs are often created during the sync operation when `en-US`
+documents get merged — for example if `Foo/Bar` becomes just a section inside
+`Foo`, and we redirect `Foo/Bar` to `Foo#Bar`. This will result in a conflict
+as the sync job tries to move the translated `Foo/Bar` to `Foo` according to the
+redirect, but `Foo` already exists.