OpenTermsArchive · Ndpnt · May 27, 2025 · May 27, 2025 · May 27, 2025 · May 28, 2025
diff --git a/content/_index.fr.md b/content/_index.fr.md
diff --git a/content/_index.md b/content/_index.md
@@ -1,39 +1,31 @@
 ---
-title: Open Terms Archive documentation
-linkTitle: Introduction
+title: Introduction
 weight: 1
 ---
 
-# Open Terms Archive documentation
+# Welcome to the Open Terms Archive documentation
 
 Open Terms Archive is a decentralised system that tracks collections of services' terms across multiple servers. Each collection exposes the data it collects through datasets and through its own API. The Federation API unifies search and discovery across collections.
 
-## Required minimal terminology
 
-Before diving into the details, let's first understand the essential terminology used throughout this documentation.
+## Documentation structure
 
-- **Terms:** the contractual documents published by services (such as Terms of Service, Privacy Policy, Community Guidelines…) that users agree to.
-- **Collection:** a set of tracked terms grouped by a specific scope (such as language, jurisdiction, industry…).
-- **Declaration:** a JSON file that defines which terms to track for a service and how to track them.
-- **Snapshot:** the original source document (HTML, PDF…) from which the terms will be extracted.
-- **Version:** the textual content of the terms after filtering out irrelevant content (navigation menu, advertisements…) from a snapshot.
+This documentation follows the [Diátaxis](https://diataxis.fr) approach and is structured in following categories
 
-## Documentation structure
+### Tutorials
+
+step-by-step learning guides that help beginners get started with Open Terms Archive, providing foundational knowledge and hands-on experience.
+
+### How-to guides
+
+Task-focused instructions that help experienced users accomplish specific goals efficiently and effectively.
+
+### References
+
+Comprehensive technical documentation detailing configuration options and specifications for advanced users.
 
-This documentation follows the [Diátaxis](https://diataxis.fr) approach and structures content in different categories:
+### Explanations
 
-- **Tutorials:** step-by-step learning guides that help beginners get started with Open Terms Archive, providing foundational knowledge and hands-on experience.
-- **How-to guides:** task-focused instructions that help experienced users accomplish specific goals efficiently and effectively.
-- **References:** comprehensive technical documentation detailing configuration options and specifications for advanced users.
-- **Explanations:** background knowledge that enables understanding the constraints and how choices that are made.
+Background knowledge that enables understanding the constraints and how choices that are made.
 
-### Table of contents
 
-- **Analysis:** guidance on how to analyze terms changes, from navigating through the history of tracked terms to publishing memos about significant changes.
-- **Community:** information on how to participate in the Open Terms Archive community.
-- **Terms:** guidance on tracking and maintaining terms declarations.
-- **Collections:** guidance on creating and managing collections of tracked terms.
-- **Federation:** constraints and benefits of joining the Open Terms Archive federation.
-- **Deployment:** guidance on operating an Open Terms Archive instance.
-- **Programmatic access:** documentation on the engine CLI and APIs.
-- **Concepts and principles:** main concepts, terminology and fundamental design principles of Open Terms Archive.
diff --git a/content/analysis/_index.fr.md b/content/analysis/_index.fr.md
diff --git a/content/analysis/_index.md b/content/analysis/_index.md
diff --git a/content/analysis/how-to/_index.md b/content/analysis/how-to/_index.md
diff --git a/content/analysis/reference/_index.fr.md b/content/analysis/reference/_index.fr.md
diff --git a/content/analysis/reference/_index.md b/content/analysis/reference/_index.md
diff --git a/content/analysis/reference/copywriting.fr.md b/content/analysis/reference/copywriting.fr.md
diff --git a/content/collections/_index.md b/content/collections/_index.md
diff --git a/content/collections/how-to/_index.md b/content/collections/how-to/_index.md
diff --git a/content/collections/reference/_index.md b/content/collections/reference/_index.md
diff --git a/content/community/_index.md b/content/community/_index.md
diff --git a/content/community/how-to/_index.md b/content/community/how-to/_index.md
diff --git a/content/concepts/_index.md b/content/concepts/_index.md
diff --git a/content/deployment/how-to/_index.md b/content/deployment/how-to/_index.md
diff --git a/content/terms/explanation/_index.md → content/explanations/_index.md b/content/terms/explanation/_index.md → content/explanations/_index.md
diff --git a/content/explanations/community/_index.md b/content/explanations/community/_index.md
@@ -0,0 +1,4 @@
+---
+title: Community
+weight: 4
+---
diff --git a/content/federation/benefits.md → ...anations/community/federation-benefits.md b/content/federation/benefits.md → ...anations/community/federation-benefits.md
@@ -1,7 +1,6 @@
 ---
-title: Benefits
+title: Federation benefits
 weight: 1
-aliases: /collections/federation/
 ---
 
 # Open Terms Archive federation
@@ -17,7 +16,7 @@ A collection that joins the federation enjoys the following benefits:
 1. Visibility on the Open Terms Archive website lists of collections and datasets.
 2. Access to the Open Terms Archive GitHub organisation, administered by the Open Terms Archive core team.
 3. Collection logo provided by the Open Terms Archive core team.
-4. Referencing in the official [collections list](https://opentermsarchive.org/collections.json), enabling off-the-shelf discovery in the [Federation API]({{< relref "api/federation" >}}).
+4. Referencing in the official [collections list](https://opentermsarchive.org/collections.json), enabling off-the-shelf discovery in the [Federation API]
 5. Referencing in the official [datasets list](https://opentermsarchive.org/datasets), providing visibility to analysts.
 6. Dedicated channel on the Open Terms Archive instant messaging system.
 7. API uptime tracking.

diff --git a/content/concepts/design-principles.md → content/explanations/design-principles.md b/content/concepts/design-principles.md → content/explanations/design-principles.md
diff --git a/content/concepts/main.md → content/explanations/main-concepts.md b/content/concepts/main.md → content/explanations/main-concepts.md
diff --git a/content/explanations/terms-tracking/_index.md b/content/explanations/terms-tracking/_index.md
@@ -0,0 +1,4 @@
+---
+title: Terms Tracking
+weight: 3
+---
diff --git a/...s/explanation/declarations-maintenance.md → ...erms-tracking/declarations-maintenance.md b/...s/explanation/declarations-maintenance.md → ...erms-tracking/declarations-maintenance.md
@@ -1,8 +1,6 @@
 ---
-title: "Declarations maintenance"
-weight: 6
-aliases:
-  - /terms/declarations-maintenance/
+title: Declarations maintenance
+weight: 1
 ---
 
 # Declarations maintenance

diff --git a/content/terms/explanation/range-selectors.md → ...nations/terms-tracking/range-selectors.md b/content/terms/explanation/range-selectors.md → ...nations/terms-tracking/range-selectors.md
@@ -1,5 +1,6 @@
 ---
 title: Range selectors
+weight: 2
 ---
 
 ## Range selectors

diff --git a/content/explanations/terms-tracking/service-name-noise.md b/content/explanations/terms-tracking/service-name-noise.md
@@ -0,0 +1,40 @@
+---
+title: Service naming
+weight: 5
+---
+
+## Service name
+
+### Casing
+
+- In order to find the service name casing, rely first on the page title (easily found in search results). Do not rely on the logo as it can be stylized differently. Example with Facebook:
+![facebook search](https://user-images.githubusercontent.com/222463/91416484-baaa3a00-e84f-11ea-94cf-8805d17aa711.png)
+- If it is still ambiguous, rely on Wikipedia as a source. However, make sure to differentiate the _service_ from the _provider_ company's name. Example with “DeviantArt”, a service (which used to be stylized deviantArt until 2014) by the limited liability company “deviantArt”:
+![deviantArt search](https://user-images.githubusercontent.com/222463/91416936-5b98f500-e850-11ea-80fe-a50be27356e3.png)
+
+### Terms used by several services
+
+- If you want to add terms which happen to be shared with another service from the same parent company, be specific in naming the exact service you want to track. For instance, you may find that a company like Github uses the same terms for its code hosting and its AI assistant. While this does not mean that the terms for GitHub (code hosting) are the only terms of GitHub Copilot (assistant), it does mean that these two services have terms that are represented in the same document. In tracking terms for one of these services, say Github Copilot, be specific in naming it as the service you want to track. This way, if GitHub was to introduce dedicated terms for each of these services in the future, their locations can be updated without having to create new terms since the service already existed before.
+
+- - -
+
+## Service ID
+
+### Normalisation
+
+1. For non-roman alphabets (Cyrillic, ideograms…), use the service-provided transliteration.
+2. For diacritics: normalise the string to its `NFD` normal UTF form, then remove the entire combining character class. [Details](https://stackoverflow.com/a/37511463/594053).
+3. As a last resort, use the domain name.
+
+### Provider prefixing
+
+- If you encounter terms you want to add to a service, yet find that it would override already-declared terms for this service such as Terms of Service or Privacy Policy, and that the only solution you see would be to create a new terms type that would contain the name of the feature, then it is likely you should declare a new service, potentially duplicating existing terms.
+
+> Example: the Facebook Community Payments terms are Terms of Service. The only way to declare them in the Facebook service would be to add a “Community Payments Terms” terms type as they would otherwise conflict with Facebook's Terms of Service. It is better to declare a new service called “Facebook Payments” with its own Terms of Service. It turns out that this service also has a developer agreement, independent from the main Facebook service.
+
+![Facebook Community Payments](https://user-images.githubusercontent.com/222463/91419033-3a85d380-e853-11ea-8468-42a536b7e87b.png)
+
+- As a last resort, rely on the trademark.
+
+Example: Apple's App Store uses only generic terms (“app” and “store”). However, it is of common use to mention “the App Store” as Apple's. To help us decide whether it should be prefixed or not, we can check that [Apple has trademarked “App Store”](https://www.apple.com/legal/intellectual-property/trademark/appletmlist.html). The service can thus be named “App Store”, without prefixing.
+
diff --git a/content/terms/explanation/terms-types.md → ...xplanations/terms-tracking/terms-types.md b/content/terms/explanation/terms-types.md → ...xplanations/terms-tracking/terms-types.md
@@ -1,7 +1,6 @@
 ---
-title: "Understanding terms types"
-linkTitle: Terms types
-weight: 1
+title: Terms categories
+weight: 3
 ---
 
 # Terms types: a foundation of a consistent archive