diff --git a/content/_index.fr.md b/content/_index.fr.md deleted file mode 100644 index 839994b3..00000000 --- a/content/_index.fr.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: "Accueil" -weight: 1 ---- - -_La documentation en français est incomplète. Vous pouvez toutefois la consulter en [langue anglaise]({{< relref path="/" lang="en" >}})._ - -... diff --git a/content/_index.md b/content/_index.md index 59da69c2..ba6ef843 100644 --- 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 deleted file mode 100644 index 1194a146..00000000 --- a/content/analysis/_index.fr.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Analyse" -weight: 2 ---- diff --git a/content/analysis/_index.md b/content/analysis/_index.md deleted file mode 100644 index 06716769..00000000 --- a/content/analysis/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Analysis" -weight: 2 ---- - diff --git a/content/analysis/how-to/_index.md b/content/analysis/how-to/_index.md deleted file mode 100644 index b4ac9c61..00000000 --- a/content/analysis/how-to/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: How to guides -weight: 1 ---- diff --git a/content/analysis/reference/_index.fr.md b/content/analysis/reference/_index.fr.md deleted file mode 100644 index 98ee9611..00000000 --- a/content/analysis/reference/_index.fr.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: References -weight: 2 ---- diff --git a/content/analysis/reference/_index.md b/content/analysis/reference/_index.md deleted file mode 100644 index 98ee9611..00000000 --- a/content/analysis/reference/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: References -weight: 2 ---- diff --git a/content/analysis/reference/copywriting.fr.md b/content/analysis/reference/copywriting.fr.md deleted file mode 100644 index 2a2476ec..00000000 --- a/content/analysis/reference/copywriting.fr.md +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Référence de rédaction de mémo -linkTitle: Rédaction de mémo -slug: /reference/redaction ---- - -# Rédaction de mémo - -Chaque mémo doit être composé des éléments détaillés ci-dessous. Vous devez suivre cette structure lors de la rédaction. - -## Titre - -- Rédiger une courte phrase déclarative pour mettre en avant le changement clé. -- 140 caractères maximum. -- Utiliser le nom du service comme sujet. -- Écrire au présent. -- Préférer les formulations actives aux formulations passives (« Meta étend la portée de… » plutôt que « La portée de… est étendue par Meta »). -- Décrire le changement de conditions et non le nom du document. Cette information sera fournie dans les métadonnées. -- Ne pas mettre de ponctuation. -- Ne pas mettre de lien dans le titre parce que dans certains contextes de réutilisation le titre en entier est un lien vers le mémo. - -**Exemples** - -> Facebook interdit aux États de nier l’usage de la force lors d’une invasion - -> Mistral traite des données à caractère personnel aux USA et cesse d’informer de tels changements - -## Nom du service - -- Écrivez le nom du service et non le nom de l'entreprise, par exemple « Facebook » plutôt que « Meta ». - -**Exemples** - -> LinkedIn - -> OpenAI - -## Type de termes - -- Vous devez renseigner un [type de termes](https://github.com/OpenTermsArchive/terms-types) valide. -- Plusieurs types de termes sont autorisés. - -**Exemples** - -> Terms of Service - -> Community Guidelines, Terms of Service, Privacy Policy - -## Date de modification - -- Utilisez le format `jour mois année`. -- Plusieurs dates sont autorisées. -- Évitez les répétitions de mois ou d'années. - -**Exemples** - -> 4 juin 2020 - -> 6 juin, 5 et 16 décembre 2023 - -## Corps de texte - -- Décrire les changements de manière neutre et objective, sans jugement. - - Écrire au passé composé (par exemple : « a ajouté », « a retiré »…). - - Mettre en gras le point le plus important. - - Ne pas rappeler la date, elle est déjà dans les métadonnées. -- Ajouter systématiquement un lien vers le diff sur ce verbe d’action. - - Titre du lien : « Voir le changement ». - - Éviter les verbes « annoncer » et équivalents, car la plupart du temps les changements détectés ne sont justement pas annoncés. -- Ne pas hésiter à citer le nouveau texte. - - Ne pas mettre les citations en italique, utiliser des guillemets. Les guillemets sont « » (avec espace insécable) en français, les guillemets sont “” (sans espace) en anglais uniquement. - - Minimiser la longueur des citations car le texte juridique est souvent très verbeux. - - Ne citer le texte avant modification que s'il est strictement nécessaire à la compréhension du changement, pour réduire les risques de confusion et la longueur. -- Si vous écrivez dans une langue différente de celle de la modification détectée, recherchez toujours les citations dans la version du document qui correspond à la langue d'écriture (si elle existe) au lieu de les traduire vous-même. - -**Exemple** - -> Mistral a [ajouté](https://github.com/OpenTermsArchive/GenAI-versions/commit/225931387dda66a4f182e78acf72feecf729136e) les États-Unis aux lieux où sont traitées les données personnelles sur son infrastructure Google Cloud Platform, alors qu'elles n’étaient auparavant traitées que dans l’UE (en Irlande). -> -> Dans ce même changement, Mistral a modifié son engagement à informer ses clients en cas de « toute modification » de la liste de ses sous-traitants, pour ne les informer qu'en cas « d'ajout ou de remplacement d’un sous-traitant ». Cela signifie ne pas informer ses clients d’un changement tel que celui qui vient d’être appliqué. En effet, Google Cloud Platform n'est ni ajouté ni retiré de la liste des sous-traitants, seulement _modifié_ pour étendre sa portée territoriale. -> -> Le fait que les données personnelles puissent désormais être traitées aux États-Unis et non plus seulement dans l'UE a de fortes implications en matière de protection de la vie privée. - - -## Exemples complets - -### Memo 1 - -> **Nouveau traceur Microsoft chez TikTok** -> -> _TikTok ▪ Trackers Policy ▪ 9 mars 2022_ -> -> Évolution discrète dans la politique de TikTok relative aux cookies : le média social ajoute [Bing Pixel](https://github.com/OpenTermsArchive/france-versions/commit/b5f7e56ccfe38a03d9fcdeae9ce80e897c8f7333?short_path=d187ffa?short_path=d187ffa#diff-d187ffa99dddfb4f2bda567ea1fa79e37ab477ff82ddedc5dad3f18394d2f981) à ses prestataires d’analyse de données analytiques et marketing. Le service de Microsoft rejoint Linkedin Insight Tag (LinkedIn est aussi propriété de Microsoft), Google Analytics et Google Ads, Apps Flyer et Facebook Pixel. - -### Memo 2 - -> **Instagram interdit le contenu qui « facilite l’infraction des droits d’auteur »** -> -> _Instagram ▪ Community Guidelines ▪ 28 mars 2022_ -> -> La partie « propriété intellectuelle » des règles de communauté d’Instagram a été [modifiée](https://github.com/OpenTermsArchive/france-elections-versions/commit/1be4b836e3012344558b60d8f9f871bc42cfa4ca?short_path=c108c01#diff-c108c013f0b8769389f20259465cb81324e805f4334bcda6931344e16f999441) le 28 mars pour interdire la publication de contenu qui « facilite l’infraction des droits d’auteur par le biais d’appareils ou services non autorisés ». Le texte présente une liste de cas dans lesquels l’internaute risquerait d’enfreindre les droits d’auteurs d’un tiers ou, ajout du jour, « de faciliter cette infraction », même s’il n’en avait pas l’intention. Derrière les cas précédemment listés, parmi lesquels « vous avez acheté ou téléchargé le contenu » ou « vous avez vu d’autres personnes publier le même contenu », Instagram ajoute que l’utilisateur risque d’enfreindre les droits d’auteurs s’il ou elle « utilise un appareil ou service de streaming non autorisé (exemples : une application ou un service “débridés” ou “chargés”) ». - -## Contextualisation (optionnel) - -- Corps du texte dans un nouveau paragraphe : contextualisation avec liens externes vers les sources les plus autoritatives possible. -- Par exemple, expliquer quels enjeux plus larges sont concernés par ce changement de politique, ou donner une perspective historique. - -**Exemple** - -> **Meta élargit ses zones d’action face à l’exploitation d’enfants** -> -> _Facebook ▪ Community Guidelines ▪ June 13, 2022_ -> -> La partie relative à l’exploitation d’enfants [s’élargit](https://github.com/OpenTermsArchive/france-elections-versions/commit/0396436542fa7ef8dd8ae4dd02ff0ed5500e08a2) pour couvrir non seulement les publications d’exploitation de mineurs, mais aussi « toute activité » relative à ce type d’actes. Meta a modifié les mêmes éléments dans les règles de communauté de Facebook et d’Instagram. -> -> Cela ouvre la question de la modération des discussions privées, alors que les plateformes sociales ont des difficultés récurrentes dans la gestion des contenus relatifs aux violences sur enfants — fin mars encore, le New-York Times [montrait](https://www.nytimes.com/2022/03/31/business/meta-child-sexual-abuse.html) que la modération reste très légère dans ce domaine, quand bien même les plateformes sont censées répertorier ce type de contenu et le [signaler aux autorités](https://www.theverge.com/2022/3/31/23005576/facebook-content-moderators-child-sexual-abuse-material-csam-policy). - -Source : [Mémo du 23 juin 2022, Édition France Élections](https://sh1.sendinblue.com/aif98ezlolpfe.html). diff --git a/content/collections/_index.md b/content/collections/_index.md deleted file mode 100644 index dfa6330b..00000000 --- a/content/collections/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Collections -weight: 5 ---- diff --git a/content/collections/how-to/_index.md b/content/collections/how-to/_index.md deleted file mode 100644 index 01a5161f..00000000 --- a/content/collections/how-to/_index.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: How to guides -weight: 2 ---- - diff --git a/content/collections/reference/_index.md b/content/collections/reference/_index.md deleted file mode 100644 index fd021bb8..00000000 --- a/content/collections/reference/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: References -weight: 3 ---- diff --git a/content/community/_index.md b/content/community/_index.md deleted file mode 100644 index c1b85428..00000000 --- a/content/community/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: "Community" -weight: 3 ---- diff --git a/content/community/how-to/_index.md b/content/community/how-to/_index.md deleted file mode 100644 index b4ac9c61..00000000 --- a/content/community/how-to/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: How to guides -weight: 1 ---- diff --git a/content/concepts/_index.md b/content/concepts/_index.md deleted file mode 100644 index 78a4c739..00000000 --- a/content/concepts/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Concepts and principles -weight: 10 ---- diff --git a/content/deployment/how-to/_index.md b/content/deployment/how-to/_index.md deleted file mode 100644 index b4ac9c61..00000000 --- a/content/deployment/how-to/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: How to guides -weight: 1 ---- diff --git a/content/terms/explanation/_index.md b/content/explanations/_index.md similarity index 100% rename from content/terms/explanation/_index.md rename to content/explanations/_index.md diff --git a/content/explanations/community/_index.md b/content/explanations/community/_index.md new file mode 100644 index 00000000..8b43f0d8 --- /dev/null +++ b/content/explanations/community/_index.md @@ -0,0 +1,4 @@ +--- +title: Community +weight: 4 +--- diff --git a/content/federation/benefits.md b/content/explanations/community/federation-benefits.md similarity index 92% rename from content/federation/benefits.md rename to content/explanations/community/federation-benefits.md index 75c4d5d0..ca001060 100644 --- a/content/federation/benefits.md +++ b/content/explanations/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 b/content/explanations/design-principles.md similarity index 100% rename from content/concepts/design-principles.md rename to content/explanations/design-principles.md diff --git a/content/concepts/main.md b/content/explanations/main-concepts.md similarity index 100% rename from content/concepts/main.md rename to content/explanations/main-concepts.md diff --git a/content/explanations/terms-tracking/_index.md b/content/explanations/terms-tracking/_index.md new file mode 100644 index 00000000..727add34 --- /dev/null +++ b/content/explanations/terms-tracking/_index.md @@ -0,0 +1,4 @@ +--- +title: Terms Tracking +weight: 3 +--- diff --git a/content/terms/explanation/declarations-maintenance.md b/content/explanations/terms-tracking/declarations-maintenance.md similarity index 98% rename from content/terms/explanation/declarations-maintenance.md rename to content/explanations/terms-tracking/declarations-maintenance.md index b572df81..ab951a5f 100644 --- a/content/terms/explanation/declarations-maintenance.md +++ b/content/explanations/terms-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 b/content/explanations/terms-tracking/range-selectors.md similarity index 99% rename from content/terms/explanation/range-selectors.md rename to content/explanations/terms-tracking/range-selectors.md index 5194574a..5576b343 100644 --- a/content/terms/explanation/range-selectors.md +++ b/content/explanations/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 new file mode 100644 index 00000000..a3d9352f --- /dev/null +++ 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 b/content/explanations/terms-tracking/terms-types.md similarity index 97% rename from content/terms/explanation/terms-types.md rename to content/explanations/terms-tracking/terms-types.md index ceaefda7..d31495aa 100644 --- a/content/terms/explanation/terms-types.md +++ b/content/explanations/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 diff --git a/content/terms/guideline/declaring.md b/content/explanations/terms-tracking/tracking-noise.md similarity index 56% rename from content/terms/guideline/declaring.md rename to content/explanations/terms-tracking/tracking-noise.md index a1cb0ee7..c8cd4ead 100644 --- a/content/terms/guideline/declaring.md +++ b/content/explanations/terms-tracking/tracking-noise.md @@ -1,49 +1,8 @@ --- -title: "Declaring terms" -aliases: - - /guidelines/declaring/ - - /terms/guidelines/declaring/ +title: Tracking noise +weight: 5 --- -# Declaring terms - -## 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. - -- - - - ## Usual noise Noise is unwanted content in versions. @@ -197,3 +156,4 @@ You can only use our copyrights or [trademarks (or any similar marks)](https://l #### Solution Write a filter in the declaration. + diff --git a/content/federation/_index.md b/content/federation/_index.md deleted file mode 100644 index 9a8971f5..00000000 --- a/content/federation/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Federation -weight: 6 ---- diff --git a/content/federation/how-to/_index.md b/content/federation/how-to/_index.md deleted file mode 100644 index b4ac9c61..00000000 --- a/content/federation/how-to/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: How to guides -weight: 1 ---- diff --git a/content/how-to/_index.md b/content/how-to/_index.md new file mode 100644 index 00000000..c009815a --- /dev/null +++ b/content/how-to/_index.md @@ -0,0 +1,6 @@ +--- +title: How-to guides +weight: 2 +--- + +# How-to guides diff --git a/content/how-to/analysis/_index.md b/content/how-to/analysis/_index.md new file mode 100644 index 00000000..4fce65c0 --- /dev/null +++ b/content/how-to/analysis/_index.md @@ -0,0 +1,4 @@ +--- +title: Terms analysis +weight: 1 +--- diff --git a/content/analysis/how-to/navigate-history.md b/content/how-to/analysis/navigate-history.md similarity index 100% rename from content/analysis/how-to/navigate-history.md rename to content/how-to/analysis/navigate-history.md diff --git a/content/terms/how-to/be-notified.md b/content/how-to/analysis/notify-changes.md similarity index 86% rename from content/terms/how-to/be-notified.md rename to content/how-to/analysis/notify-changes.md index 417f18e5..b3721af1 100644 --- a/content/terms/how-to/be-notified.md +++ b/content/how-to/analysis/notify-changes.md @@ -1,10 +1,6 @@ --- -title: How to be notified of terms changes -weight: 4 -linkTitle: Be notified of changes -aliases: - - /subscribe-rss/ - - /terms/how-to-be-notified-of-terms-changes/ +title: Monitor terms changes +weight: 2 --- # How to be notified of terms changes @@ -17,9 +13,9 @@ An RSS feed is a type of web page that contains information about the latest con To find out the address of the RSS feed you want to subscribe to: -1. [Navigate]({{< relref "/analysis/how-to/navigate-history" >}}) to the page with the history of changes you are interested in. +1. [Navigate]({{< relref "/how-to/analysis/navigate-history" >}}) to the page with the history of changes you are interested in. - For example, for the GitHub Privacy Policy of the Demo collection, this would be [this page](https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md). -2. Copy the address of that page from your browser’s address bar. +2. Copy the address of that page from your browser's address bar. - In the address, if they are present, replace the words `blob` or `tree` with `commits`. - For example, for the GitHub Privacy Policy of the Demo collection, this would be `https://github.com/OpenTermsArchive/demo-versions/commits/main/GitHub/Privacy%20Policy.md`. 3. Append `.atom` at the end of this address. diff --git a/content/analysis/how-to/publish-memo.md b/content/how-to/analysis/publish-memo.md similarity index 91% rename from content/analysis/how-to/publish-memo.md rename to content/how-to/analysis/publish-memo.md index a488e812..5d14306f 100644 --- a/content/analysis/how-to/publish-memo.md +++ b/content/how-to/analysis/publish-memo.md @@ -1,7 +1,6 @@ --- -title: Publish a memo -aliases: - - /memos/how-to-publish/ +title: Publish memos +weight: 4 --- # How to publish a memo @@ -12,7 +11,7 @@ No technical skills are required. ## Prerequisites -- A drafted memo compliant with the [copywriting reference]({{< relref "/analysis/reference/copywriting" >}}). +- A drafted memo compliant with the copywriting reference. ## 1. Send diff --git a/content/how-to/collection-lifecycle/_index.md b/content/how-to/collection-lifecycle/_index.md new file mode 100644 index 00000000..69dd222e --- /dev/null +++ b/content/how-to/collection-lifecycle/_index.md @@ -0,0 +1,4 @@ +--- +title: Collection lifecycle +weight: 3 +--- diff --git a/content/collections/how-to/create.md b/content/how-to/collection-lifecycle/create-collection.md similarity index 81% rename from content/collections/how-to/create.md rename to content/how-to/collection-lifecycle/create-collection.md index c48a4295..153a7392 100644 --- a/content/collections/how-to/create.md +++ b/content/how-to/collection-lifecycle/create-collection.md @@ -1,6 +1,6 @@ --- title: Create a collection -weight: 1 +weight: 2 --- # How to create a collection @@ -9,7 +9,7 @@ You are considering creating a new collection to track terms with Open Terms A ## Define metadata -First of all, define the [metadata]({{< relref "collections/reference/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories. +First of all, define the [metadata]({{< relref "/reference/collection/metadata" >}}) of the collection you would like to create and keep them ready to be used when setting up the repositories. ## Check existing collections @@ -25,10 +25,10 @@ You can inform the community by posting on the instant messaging system, or [sen ## Define governance -Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the [governance]({{< relref "collections/reference/governance" >}}) of your collection. +Setting up and maintaining a collection over time needs fulfilling certain tasks on a regular basis. These tasks are handled through roles. To make sure that all these roles are covered, define the [governance]({{< relref "/reference/collection/roles" >}}) of your collection. At any time, feel free to ask for help or partners in the community. ## Create repositories -See the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}}) for your collection. +See the [guide to create repositories]({{< relref "/how-to/collection-lifecycle/create-repositories" >}}) for your collection. diff --git a/content/collections/how-to/create-repositories.md b/content/how-to/collection-lifecycle/create-repositories.md similarity index 99% rename from content/collections/how-to/create-repositories.md rename to content/how-to/collection-lifecycle/create-repositories.md index 8884aedd..3492bc4d 100644 --- a/content/collections/how-to/create-repositories.md +++ b/content/how-to/collection-lifecycle/create-repositories.md @@ -1,6 +1,6 @@ --- title: Create repositories -weight: 2 +weight: 3 --- # How to create collection repositories diff --git a/content/collections/how-to/define-metadata.md b/content/how-to/collection-lifecycle/define-metadata.md similarity index 99% rename from content/collections/how-to/define-metadata.md rename to content/how-to/collection-lifecycle/define-metadata.md index d4d8817b..577bbfee 100644 --- a/content/collections/how-to/define-metadata.md +++ b/content/how-to/collection-lifecycle/define-metadata.md @@ -1,6 +1,6 @@ --- title: Define metadata -weight: 3 +weight: 4 --- # How to define metadata diff --git a/content/terms/guideline/reviewing.md b/content/how-to/collection-lifecycle/review-contributions.md similarity index 89% rename from content/terms/guideline/reviewing.md rename to content/how-to/collection-lifecycle/review-contributions.md index 6a44399f..26a2b43b 100644 --- a/content/terms/guideline/reviewing.md +++ b/content/how-to/collection-lifecycle/review-contributions.md @@ -1,5 +1,5 @@ --- -title: "Reviewing contributions" +title: "Review contributions" aliases: - /guidelines/reviewing/ - /terms/guidelines/reviewing/ @@ -55,11 +55,10 @@ Your focus should be on two aspects: accuracy and quality. 1. Click on the _Inspect the declaration_ link to view the declaration in a graphical user interface. 2. Use the link provided in the URL section of the contribution tool to check out the original document. -3. Verify that the name of the service matches the JSON file and complies with the [guidelines]({{< relref "terms/guideline/declaring#service-name" >}}). +3. Verify that the name of the service matches the JSON file and complies with the [guidelines]({{< relref "/how-to/tracking/track-new-terms#service-name" >}}). 4. Quickly scan the document to ensure that the correct term type has been selected. To determine the term type, consider who the intended audience is and what the document is discussing. You can also refer to the [terms types list](https://github.com/OpenTermsArchive/terms-types/blob/main/termsTypes.json) to find the best term type for the document. 5. Confirm that the selected area of the document contains only one term type and does not include any other types. -6. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the [selectors guidelines]({{< relref "terms/guideline/choosing-selectors" >}}). - - Ensure that the significant parts do not include navigation items, contact links, or other insignificant details that may cause confusion by triggering a change detection when the legal terms have actually not been updated. +6. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the selectors guidelines. 7. Verify the version of the document in the contribution tool by clicking on the _Verify version_ button. 8. Ensure that all checks generated by the OTA-bot are manually checked. 9. When you confirm that the term contribution has been made to the correct collection, proceed to add a review. @@ -74,19 +73,19 @@ The pull request created will consist of fewer checks than those that add declar For pull requests that update declarations, you should focus should be on two things: history file and declaration. -- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "terms/explanation/declarations-maintenance" >}}). +- **History file:** The history file is a JSON file that keeps track of a service declaration changes. It contains a `validUntil` property that specifies the date a specific version of a service declaration was last effective. You have to confirm that this date is the same as the date in the issue opened for the declaration when the bot couldn't track it for the first time. This issue is usually included in the pull request message. The history file is updated with every `update` pull request. You can find more information about the history file [here]({{< relref "/explanations/terms-tracking/declarations-maintenance" >}}). - **Declaration:** for `update` pull requests, you only look at the selectors to make sure they are **simple** and also verify the **generated version** is ok. ### Step-by-step Review Guide 1. Click on the inspect the declaration suggestion link to view contribution using the contribution tool. -2. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the [selectors guidelines]({{< relref "terms/guideline/choosing-selectors" >}}). +2. Check both the significant and insignificant parts of the document. Ensure that the suggested selectors abide by the selectors guidelines. 3. Verify the version of the document in the contribution tool by clicking on the `verify version` button. 4. Open the issue linked with the pull request. Confirm the date when the declaration was last tracked from the bot's comment. 5. Compare it with the `validUntil` property in the history file under the `Files changes` section of the pull request. If the dates are the same, proceed to approve the pull request. 6. Merge the contribution. -You can read more about maintaining declarations from the [official documentation]({{< relref "terms/explanation/declarations-maintenance" >}}). +You can read more about maintaining declarations from the official documentation. ## When to Make Changes to a Contribution @@ -96,7 +95,7 @@ In some special cases, the correction may have to do with the service name. Such ### Editing a Service ID -When contributing to the project, reviewers may need to modify the Service ID of a service that is being added for tracking. This is often necessary when the service being tracked is in a language other than English, such as Chinese or French. In these cases, the Service ID usually reflects the transliteration of the service name (written in the native language). The [documentation]({{< relref "terms/reference#service-id" >}}) provides more information on this. It is important to note that the contributor can be very crucial in providing an accurate transliteration of the service name especially if the reviewer does not know the service's native language. +When contributing to the project, reviewers may need to modify the Service ID of a service that is being added for tracking. This is often necessary when the service being tracked is in a language other than English, such as Chinese or French. In these cases, the Service ID usually reflects the transliteration of the service name (written in the native language). The [documentation]({{< relref "/how-to/tracking/track-new-terms#service-id" >}}) provides more information on this. It is important to note that the contributor can be very crucial in providing an accurate transliteration of the service name especially if the reviewer does not know the service's native language. Since the Service ID is used as the file name of the JSON file associated with the service, it is necessary to change the file name to reflect the transliteration. Here are the steps to follow: @@ -108,9 +107,9 @@ Since the Service ID is used as the file name of the JSON file associated with t ## Running Tests -Status checks are required to pass before merging can take place. This ensures that automated tests (through “Continuous Integration”, or CI) confirm the contribution will be readable by the Open Terms Archive engine. +Status checks are required to pass before merging can take place. This ensures that automated tests (through "Continuous Integration", or CI) confirm the contribution will be readable by the Open Terms Archive engine. -These tests should run automatically. However, under some circumstances, the tests might need to be triggered manually. To that end, navigate to the “Actions” tab of the collections repository, and look for the name of the contribution where tests are not run. Once located in the list, click on the entry name, and click on “Re-run all jobs” at the top right. +These tests should run automatically. However, under some circumstances, the tests might need to be triggered manually. To that end, navigate to the "Actions" tab of the collections repository, and look for the name of the contribution where tests are not run. Once located in the list, click on the entry name, and click on "Re-run all jobs" at the top right. ### Running Tests From a Fork @@ -152,8 +151,8 @@ For example, tests may fail in CI because of a 403 Access Denied error, but succ ## Merging the Pull Request -Beyond status checks, additional restriction requires branches to be up to date before merging. This ensures that the contribution has been tested with the latest version of the collection. This appears as a _“This branch is out-of-date with the base branch”_ warning on a pull request. -You can fix this using the Github interface, by clicking on the arrow button next to the “Update Branch” button, and select “Update with Rebase”. +Beyond status checks, additional restriction requires branches to be up to date before merging. This ensures that the contribution has been tested with the latest version of the collection. This appears as "_This branch is out-of-date with the base branch_" warning on a pull request. +You can fix this using the Github interface, by clicking on the arrow button next to the "Update Branch" button, and select "Update with Rebase". ## Contributions FAQ diff --git a/content/collections/how-to/take-over.md b/content/how-to/collection-lifecycle/take-over.md similarity index 51% rename from content/collections/how-to/take-over.md rename to content/how-to/collection-lifecycle/take-over.md index 4b970f38..166a275d 100644 --- a/content/collections/how-to/take-over.md +++ b/content/how-to/collection-lifecycle/take-over.md @@ -1,22 +1,22 @@ --- title: Take over a collection -weight: 5 +weight: 6 --- # How to take over a collection -Before starting, ensure the collection is either [abandoned]({{< relref "collections/reference/status#abandoned" >}}) or [terminated]({{< relref "collections/reference/status#terminated" >}}). In any case, keep all original licenses, history, and attributions. +Before starting, ensure the collection is either [abandoned]({{< relref "/reference/collection/status#abandoned" >}}) or [terminated]({{< relref "/reference/collection/status#terminated" >}}). In any case, keep all original licenses, history, and attributions. ## Steps -1. If the approval is not explicitly given in the collection's README, get it by contacting owners via email if publicly available, a GitHub issue on the collection repository, or on the [community chat]({{< relref "community/how-to/join" >}}). +1. If the approval is not explicitly given in the collection's README, get it by contacting owners via email if publicly available, a GitHub issue on the collection repository, or on the community chat. 2. Ask the owners to transfer the repositories to your organization. -3. Check that the transferred declarations, snapshots and versions repositories are [properly configured]({{< relref "/collections/how-to/create-repositories" >}}). +3. Check that the transferred declarations, snapshots and versions repositories are [properly configured]({{< relref "/how-to/collection-lifecycle/create-repositories" >}}). -4. Update the governance in the README files and in the [collection metadata]({{< relref "/collections/how-to/define-metadata" >}}) in the declarations repository. +4. Update the governance in the README files and in the [collection metadata]({{< relref "/how-to/collection-lifecycle/define-metadata" >}}) in the declarations repository. -5. Set up continous integration and deployment to [deploy the collection]({{< relref "/deployment/how-to/deploy" >}}) on your servers. +5. Set up continous integration and deployment to deploy the collection on your servers. Congratulations and thanks! You are now officially maintaining the collection. diff --git a/content/collections/how-to/terminate.md b/content/how-to/collection-lifecycle/terminate-collection.md similarity index 65% rename from content/collections/how-to/terminate.md rename to content/how-to/collection-lifecycle/terminate-collection.md index 608e6cda..aadfe5b3 100644 --- a/content/collections/how-to/terminate.md +++ b/content/how-to/collection-lifecycle/terminate-collection.md @@ -1,6 +1,6 @@ --- title: Terminate a collection -weight: 4 +weight: 5 --- # How to terminate a collection @@ -9,13 +9,13 @@ If you don't have the resources to maintain a collection anymore, follow these s ## Steps -1. Announce the intention to terminate the collection in the [community chat]({{< relref "/federation/how-to/join" >}}) to inform users and make potential new maintainers aware. Give at least one month notice to that others have time to share their intention to take over the collection before proceeding to the next step. +1. Announce the intention to terminate the collection in the community chat to inform users and make potential new maintainers aware. Give at least one month notice to that others have time to share their intention to take over the collection before proceeding to the next step. If no-one has come forward after one month, you can proceed to the next step. -2. In the declarations repository's README, state that the collection is [terminated]({{< relref "collections/reference/status#terminated" >}}), encourage community to take it over. It can be done by adding the following snippet on the top of the file: +2. In the declarations repository's README, state that the collection is [terminated]({{< relref "/reference/collection/status#terminated" >}}), encourage community to take it over. It can be done by adding the following snippet on the top of the file: -> This collection is no longer actively maintained since ``. New maintainers are encouraged to take over the operation of this collection in order to resume tracking its terms. Guidance on [taking over maintenance]({{< relref "collections/how-to/take-over" >}}) can be found in the Open Terms Archive documentation, and help is available in the Open Terms Archive [community chat]({{< relref "/federation/how-to/join" >}}). +> This collection is no longer actively maintained since ``. New maintainers are encouraged to take over the operation of this collection in order to resume tracking its terms. Guidance on [taking over maintenance]({{< relref "/how-to/collection-lifecycle/take-over" >}}) can be found in the Open Terms Archive documentation, and help is available in the Open Terms Archive community chat. 3. [Archive](https://docs.github.com/en/repositories/archiving-a-github-repository/archiving-repositories) the collection's repositories (declarations, snapshots, versions) to prevent further commits and signal the end of activity. diff --git a/content/terms/guideline/_index.md b/content/how-to/community/_index.md similarity index 50% rename from content/terms/guideline/_index.md rename to content/how-to/community/_index.md index 82f8dd80..3c6fc347 100644 --- a/content/terms/guideline/_index.md +++ b/content/how-to/community/_index.md @@ -1,4 +1,4 @@ --- -title: Guidelines +title: Community weight: 5 --- diff --git a/content/community/how-to/join.md b/content/how-to/community/join-chat.md similarity index 94% rename from content/community/how-to/join.md rename to content/how-to/community/join-chat.md index 5ad18c0d..98be04ca 100644 --- a/content/community/how-to/join.md +++ b/content/how-to/community/join-chat.md @@ -1,10 +1,6 @@ --- -title: Join the community chat -aliases: - - /community/how-to-join-mattermost/ - - /community/how-to/join-mattermost/ - - /community/how-to/join-community-chat/ -linkTitle: Join the chat +title: Join the chat +weight: 3 --- # How to join the community chat diff --git a/content/federation/how-to/join.md b/content/how-to/community/join-federation.md similarity index 98% rename from content/federation/how-to/join.md rename to content/how-to/community/join-federation.md index 7e07c071..d7409e72 100644 --- a/content/federation/how-to/join.md +++ b/content/how-to/community/join-federation.md @@ -1,6 +1,6 @@ --- title: Join the federation -weight: 3 +weight: 2 --- # How to join the federation diff --git a/content/deployment/_index.md b/content/how-to/deployment/_index.md similarity index 72% rename from content/deployment/_index.md rename to content/how-to/deployment/_index.md index 7eb4a20a..8092b410 100644 --- a/content/deployment/_index.md +++ b/content/how-to/deployment/_index.md @@ -1,4 +1,4 @@ --- title: Deployment -weight: 7 +weight: 4 --- diff --git a/content/deployment/how-to/setup-github-teams.md b/content/how-to/deployment/github-teams.md similarity index 100% rename from content/deployment/how-to/setup-github-teams.md rename to content/how-to/deployment/github-teams.md diff --git a/content/deployment/how-to/deploy.md b/content/how-to/deployment/overview.md similarity index 98% rename from content/deployment/how-to/deploy.md rename to content/how-to/deployment/overview.md index ce2a5878..64649d1e 100644 --- a/content/deployment/how-to/deploy.md +++ b/content/how-to/deployment/overview.md @@ -11,9 +11,9 @@ This guide will help you deploy an Open Terms Archive collection to a server. Th Before starting, ensure you have: -- A basic understanding of the [deployment architecture]({{< relref "deployment/reference/architecture" >}}) +- A basic understanding of the [deployment architecture]({{< relref "/reference/deployment/architecture" >}}) - A server with admin access -- All collections repositories created, if not, see the [guide to create repositories]({{< relref "collections/how-to/create-repositories" >}}) +- All collections repositories created, if not, see the [guide to create repositories]({{< relref "/how-to/collection-lifecycle/create-repositories" >}}) - At least one declaration added to your collection - A GitHub user account to automate actions such as committing entries in versions and snapshots repositories, reporting issues when tracking fails, publishing releases… - [Ansible](https://docs.ansible.com/ansible/latest/installation_guide/intro_installation.html) installed on your local machine diff --git a/content/how-to/tracking/_index.md b/content/how-to/tracking/_index.md new file mode 100644 index 00000000..884d143a --- /dev/null +++ b/content/how-to/tracking/_index.md @@ -0,0 +1,4 @@ +--- +title: Terms tracking +weight: 2 +--- diff --git a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md b/content/how-to/tracking/get-valid-until.md similarity index 90% rename from content/terms/how-to/get-the-validUntil-date-from-an-issue.md rename to content/how-to/tracking/get-valid-until.md index b24ae946..cd973349 100644 --- a/content/terms/how-to/get-the-validUntil-date-from-an-issue.md +++ b/content/how-to/tracking/get-valid-until.md @@ -1,7 +1,6 @@ --- -title: How to get the `validUntil` date -linkTitle: Get the `validUntil` date -weight: 7 +title: Define validity periods +weight: 5 --- # How to get the `validUntil` date diff --git a/content/terms/how-to/manage-custom-terms-type.md b/content/how-to/tracking/manage-custom-terms.md similarity index 93% rename from content/terms/how-to/manage-custom-terms-type.md rename to content/how-to/tracking/manage-custom-terms.md index 871f1d30..3e1647c6 100644 --- a/content/terms/how-to/manage-custom-terms-type.md +++ b/content/how-to/tracking/manage-custom-terms.md @@ -1,15 +1,16 @@ --- -title: Manage a custom terms type -weight: 4 +title: Manage custom terms types +weight: 6 --- + # How to manage a custom terms type When tracking terms and conditions across different services, you might encounter situations where a service uses terms types that aren't yet supported by Open Terms Archive. This guide will help you handle these custom terms types effectively, whether you're working on a new collection or expanding an existing one. -_To better understand what terms types are and how they work, you can read our [detailed explanation]({{< relref "terms/explanation/terms-types" >}})._ +_To better understand what terms types are and how they work, you can read our [detailed explanation]({{< relref "/explanations/terms-tracking/terms-types" >}})._ ## Prerequisites @@ -19,7 +20,7 @@ Review the [supported types list](https://github.com/OpenTermsArchive/terms-type - If it does, use the associated type in your declaration. - If you are sure it's not supported, you can proceed with the following steps. -- If you're unsure, you can ask for help in the [Open Terms Archive community]({{< relref "community/how-to/join" >}}). +- If you're unsure, you can ask for help in the [Open Terms Archive community]({{< relref "/how-to/community/join-chat" >}}). ## Long-term solution diff --git a/content/how-to/tracking/rename-service.md b/content/how-to/tracking/rename-service.md new file mode 100644 index 00000000..de1edd51 --- /dev/null +++ b/content/how-to/tracking/rename-service.md @@ -0,0 +1,8 @@ +--- +title: Update service names +weight: 7 +--- + +# How to rename a service + +The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "/how-to/tracking/track-new-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms. diff --git a/content/terms/how-to/terminate-a-service.md b/content/how-to/tracking/terminate-service.md similarity index 88% rename from content/terms/how-to/terminate-a-service.md rename to content/how-to/tracking/terminate-service.md index 91f456a6..797af4dd 100644 --- a/content/terms/how-to/terminate-a-service.md +++ b/content/how-to/tracking/terminate-service.md @@ -1,9 +1,9 @@ --- -title: How to terminate a service -linkTitle: Terminate a service -weight: 6 +title: End service tracking +weight: 8 --- + # How to terminate a service If the service provider stops offering a service, the associated terms will become unavailable. To mark that service termination in Open Terms Archive and ensure tracking tentatives are stopped, while maintaining the possibility to explore the history: diff --git a/content/terms/how-to/test-declarations.md b/content/how-to/tracking/test-declarations.md similarity index 92% rename from content/terms/how-to/test-declarations.md rename to content/how-to/tracking/test-declarations.md index fdff130c..5afefa60 100644 --- a/content/terms/how-to/test-declarations.md +++ b/content/how-to/tracking/test-declarations.md @@ -1,11 +1,9 @@ --- -title: How to test your declarations -weight: 3 -linkTitle: Test declarations -aliases: - - /terms/how-to/test-declaration/ +title: Validate declarations +weight: 4 --- + # How to test your declarations When creating or modifying service declarations, it’s important to verify they work as expected before starting to track in production. The Open Terms Archive engine provides automated testing tools to that end. diff --git a/content/terms/how-to/track-terms.md b/content/how-to/tracking/track-new-terms.md similarity index 85% rename from content/terms/how-to/track-terms.md rename to content/how-to/tracking/track-new-terms.md index 5946b964..da133494 100644 --- a/content/terms/how-to/track-terms.md +++ b/content/how-to/tracking/track-new-terms.md @@ -1,9 +1,6 @@ --- -title: Track new terms -weight: 1 -aliases: - - /contributing-terms/ - - /terms/how-to/track-new-terms/ +title: Track new services +weight: 2 --- # How to track new terms @@ -31,11 +28,11 @@ To add a declaration, you need to follow these steps: 6. After you've properly added your selectors and structured your JSON file, you need to test and validate your JSON file to make sure it is ok. To do this, you need to run `npx ota validate --services [service name]` from the root of the repository. This will run a validation on the declaration, highlighting any changes required. 7. If all tests are good, make a pull request to the main repository. -> If you have a hard time finding the service name, check out the [practical guidelines to find the service name]({{< relref "/terms/guideline/declaring" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂 +> If you have a hard time finding the service name, check out the practical guidelines to find the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂 ## Service name -The service name is exposed to end users. It should reflect as closely as possible the official service name, as referenced in the terms or “about” pages, so that it can be recognised easily and unambiguously. +The service name is exposed to end users. It should reflect as closely as possible the official service name, as referenced in the terms or "about" pages, so that it can be recognised easily and unambiguously. - The service name should be the one used by the service itself, no matter the alphabet, UTF symbols, spaces, and casing. - _Example: `eBay`_. @@ -53,7 +50,7 @@ The service name is exposed to end users. It should reflect as closely as possib - _Example: `Firebase` (by Google) → `Firebase`_. - _Example: `App Store` (by Apple) → `App Store`_. -> If you have a hard time finding the service name, check out the [practical guidelines to find the service name]({{< relref "/terms/guideline/declaring#service-name" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂 +> If you have a hard time finding the service name, check out the practical guidelines to find the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service name if necessary 🙂 ## Service ID @@ -73,7 +70,7 @@ The service ID is exposed to developers. It should be easy to handle with script - _Example: `App Store` → `App Store`_. - _Example: `DeviantArt` → `DeviantArt`_. -> If you have a hard time defining the service ID, check out the [practical guidelines to derive the ID from the service name]({{< relref "/terms/guideline/declaring#service-id" >}}), and feel free to mention your uncertainties in the pull request! We will help you improve the service ID if necessary 🙂 +> If you have a hard time defining the service ID, check out the practical guidelines to derive the ID from the service name, and feel free to mention your uncertainties in the pull request! We will help you improve the service ID if necessary 🙂 > More details on the ID and naming constraints and recommendations can be found in the relevant [decision record](https://github.com/OpenTermsArchive/engine/blob/main/decision-records/0001-service-name-and-id.md). diff --git a/content/terms/how-to/track-terms-using-UI.md b/content/how-to/tracking/track-with-ui.md similarity index 78% rename from content/terms/how-to/track-terms-using-UI.md rename to content/how-to/tracking/track-with-ui.md index 80e3bcce..b38857a3 100644 --- a/content/terms/how-to/track-terms-using-UI.md +++ b/content/how-to/tracking/track-with-ui.md @@ -1,10 +1,6 @@ --- -title: How to track terms using the graphical contribution interface -weight: 2 -linkTitle: Track terms with UI -aliases: - - /terms/how-to-add-terms-using-with-the-graphical-contribution-interface/ - - /terms/how-to/add-terms-using-ui/ +title: Track services with UI +weight: 3 --- # How to track terms using the graphical contribution interface diff --git a/content/terms/tutorial/track.md b/content/quick-start.md similarity index 97% rename from content/terms/tutorial/track.md rename to content/quick-start.md index 07028dfd..274b500e 100644 --- a/content/terms/tutorial/track.md +++ b/content/quick-start.md @@ -1,7 +1,6 @@ --- -title: Track your first terms -aliases: - - /terms/tutorials/track/ +title: Quick Start +weight: 2 --- # Track your first terms @@ -86,4 +85,3 @@ For this tutorial, we will use the Privacy Policy of Open Terms Archive as an ex 3. Verify the results by checking the extracted version in `./data/versions/Open Terms Archive/Privacy Policy.md` file, which should contain only the meaningful content of the Privacy Policy in Markdown format. Congratulations! You have tracked your first terms locally. - diff --git a/content/deployment/reference/_index.md b/content/reference/_index.md similarity index 71% rename from content/deployment/reference/_index.md rename to content/reference/_index.md index 6f4fd0f8..63aae4a6 100644 --- a/content/deployment/reference/_index.md +++ b/content/reference/_index.md @@ -1,4 +1,4 @@ --- title: Reference -weight: 2 +weight: 3 --- diff --git a/content/reference/analysis/_index.md b/content/reference/analysis/_index.md new file mode 100644 index 00000000..4fce65c0 --- /dev/null +++ b/content/reference/analysis/_index.md @@ -0,0 +1,4 @@ +--- +title: Terms analysis +weight: 1 +--- diff --git a/content/analysis/reference/copywriting.md b/content/reference/analysis/memo-copywriting.md similarity index 98% rename from content/analysis/reference/copywriting.md rename to content/reference/analysis/memo-copywriting.md index d9462a9d..b3e76fc7 100644 --- a/content/analysis/reference/copywriting.md +++ b/content/reference/analysis/memo-copywriting.md @@ -1,6 +1,6 @@ --- -title: Memo copywriting reference -aliases: /memos/copywriting-reference/ +title: Memo copywriting +weight: 1 --- # Memo copywriting diff --git a/content/community/reference/_index.md b/content/reference/collection/_index.md similarity index 50% rename from content/community/reference/_index.md rename to content/reference/collection/_index.md index fd021bb8..1ae9eac3 100644 --- a/content/community/reference/_index.md +++ b/content/reference/collection/_index.md @@ -1,4 +1,4 @@ --- -title: References +title: Collection weight: 3 --- diff --git a/content/collections/reference/configuration.md b/content/reference/collection/configuration.md similarity index 99% rename from content/collections/reference/configuration.md rename to content/reference/collection/configuration.md index ec4be876..8619fc22 100644 --- a/content/collections/reference/configuration.md +++ b/content/reference/collection/configuration.md @@ -1,6 +1,6 @@ --- title: Configuration -weight: 3 +weight: 4 --- # Configuration options diff --git a/content/collections/reference/environment-variables.md b/content/reference/collection/environment-variables.md similarity index 100% rename from content/collections/reference/environment-variables.md rename to content/reference/collection/environment-variables.md diff --git a/content/collections/reference/metadata.md b/content/reference/collection/metadata.md similarity index 99% rename from content/collections/reference/metadata.md rename to content/reference/collection/metadata.md index b124420a..7dc77d0f 100644 --- a/content/collections/reference/metadata.md +++ b/content/reference/collection/metadata.md @@ -1,7 +1,6 @@ --- title: Metadata weight: 2 -aliases: /collections/metadata/ --- # Collection metadata diff --git a/content/collections/reference/governance.md b/content/reference/collection/roles.md similarity index 97% rename from content/collections/reference/governance.md rename to content/reference/collection/roles.md index a53a1667..cb4560f7 100644 --- a/content/collections/reference/governance.md +++ b/content/reference/collection/roles.md @@ -1,7 +1,6 @@ --- -title: Governance +title: Roles weight: 1 -aliases: /collections/governance/ --- # Collection governance diff --git a/content/collections/reference/status.md b/content/reference/collection/status.md similarity index 83% rename from content/collections/reference/status.md rename to content/reference/collection/status.md index a06a67e3..66606f0e 100644 --- a/content/collections/reference/status.md +++ b/content/reference/collection/status.md @@ -1,6 +1,6 @@ --- title: Status -weight: 5 +weight: 3 --- # Collection status @@ -13,7 +13,7 @@ The optimal operational state for a collection. - The collection saves records regularly through actively maintained and updated terms declarations. The number of tracked terms remains stable or increases over time. The versions quality is high. - Technical maintenance includes regular dependency updates, access to the latest engine features, and benefits from all infrastructure updates. -- All [roles]({{< relref "collections/reference/governance" >}}) are fulfilled. +- All [roles]({{< relref "/reference/collection/roles" >}}) are fulfilled. --- @@ -23,7 +23,7 @@ Collection may be functional but shows clear signs of neglect. - Operational status has deteriorated significantly with unknown record saving status, no updates to terms declarations, declining number of tracked terms, and decreasing versions quality. - Technical maintenance has ceased completely, with no dependency updates, missing latest engine features, and no infrastructure updates. -- All [roles]({{< relref "collections/reference/governance" >}}) are inactive. +- All [roles]({{< relref "/reference/collection/roles" >}}) are inactive. --- @@ -33,4 +33,4 @@ Collection has voluntarily ceased all operational activities. - No terms are tracked anymore, though historical records remain accessible for reference purposes. - No technical maintenance is performed. -- All [roles]({{< relref "collections/reference/governance" >}}) are inactive. +- All [roles]({{< relref "/reference/collection/roles" >}}) are inactive. diff --git a/content/reference/community/_index.md b/content/reference/community/_index.md new file mode 100644 index 00000000..3c6fc347 --- /dev/null +++ b/content/reference/community/_index.md @@ -0,0 +1,4 @@ +--- +title: Community +weight: 5 +--- diff --git a/content/community/reference/community-call.jpg b/content/reference/community/community-call.jpg similarity index 100% rename from content/community/reference/community-call.jpg rename to content/reference/community/community-call.jpg diff --git a/content/community/reference/community-call.md b/content/reference/community/community-calls.md similarity index 96% rename from content/community/reference/community-call.md rename to content/reference/community/community-calls.md index 5a58d28a..16d3e7db 100644 --- a/content/community/reference/community-call.md +++ b/content/reference/community/community-calls.md @@ -1,5 +1,6 @@ --- -title: Community call +title: Community calls +weight: 3 --- # Community call diff --git a/content/federation/reference/criteria.md b/content/reference/community/federation-criteria.md similarity index 84% rename from content/federation/reference/criteria.md rename to content/reference/community/federation-criteria.md index a4c5a831..488bb62a 100644 --- a/content/federation/reference/criteria.md +++ b/content/reference/community/federation-criteria.md @@ -1,14 +1,14 @@ --- -title: Criteria -weight: 3 +title: Federation criteria +weight: 2 --- # Federation criteria A **collection** can **join** the Open Terms Archive **federation** if it abides by the following quality criteria: -1. Clearly defined [collection metadata]({{< relref "collections/reference/metadata" >}}). -2. Clearly defined [collection governance]({{< relref "collections/reference/governance" >}}). +1. Clearly defined [collection metadata]({{< relref "/reference/collection/metadata" >}}). +2. Clearly defined collection governance. 3. The vast majority of **versions** are readable, as evidenced by a sample assessment. 4. **Frequency** of at least one track a day, as evidenced by snapshots. 5. Public and open-licensed **declarations**, as evidenced by the `LICENSE` file in the declarations repository. @@ -18,7 +18,7 @@ A **collection** can **join** the Open Terms Archive **federation** if it abides 9. Publicly accessible API with median response time under 20ms, as evidenced by uptime tracking logs. 10. Abide by all Open Terms Archive software and data licenses. -For detailed instructions on joining the federation, refer to the [How to Join the Federation guide]({{< relref "federation/how-to/join" >}}). +For detailed instructions on joining the federation, refer to the How to Join the Federation guide. ## Disclaimer diff --git a/content/federation/reference/_index.md b/content/reference/deployment/_index.md similarity index 50% rename from content/federation/reference/_index.md rename to content/reference/deployment/_index.md index 98ee9611..eaf782e3 100644 --- a/content/federation/reference/_index.md +++ b/content/reference/deployment/_index.md @@ -1,4 +1,4 @@ --- -title: References +title: Deployment weight: 2 --- diff --git a/content/deployment/reference/architecture.md b/content/reference/deployment/architecture.md similarity index 99% rename from content/deployment/reference/architecture.md rename to content/reference/deployment/architecture.md index cb52c044..408d54aa 100644 --- a/content/deployment/reference/architecture.md +++ b/content/reference/deployment/architecture.md @@ -1,5 +1,5 @@ --- -title: Deployment architecture +title: System architecture linkTitle: Architecture weight: 1 --- diff --git a/content/deployment/reference/server-specifications.md b/content/reference/deployment/server-specifications.md similarity index 81% rename from content/deployment/reference/server-specifications.md rename to content/reference/deployment/server-specifications.md index ace8b936..e97275f6 100644 --- a/content/deployment/reference/server-specifications.md +++ b/content/reference/deployment/server-specifications.md @@ -41,4 +41,4 @@ Please [report](https://github.com/OpenTermsArchive/engine/issues/new) any incom ## Location -Servers must be physically located in geographic regions that belong to the jurisdiction the collection targets to ensure to [obtain documents like a user would]({{< relref "concepts/design-principles#3-obtain-documents-like-a-user-would" >}}). This is crucial because some services deliver different versions of documents based on the inferred location of the request, even when the documents are supposed to be identical and located at the same URL. +Servers must be physically located in geographic regions that belong to the jurisdiction the collection targets to ensure to obtain documents like a user would. This is crucial because some services deliver different versions of documents based on the inferred location of the request, even when the documents are supposed to be identical and located at the same URL. diff --git a/content/api/_index.md b/content/reference/programmatic-access/_index.md similarity index 77% rename from content/api/_index.md rename to content/reference/programmatic-access/_index.md index 99349a05..61b1ae8f 100644 --- a/content/api/_index.md +++ b/content/reference/programmatic-access/_index.md @@ -1,4 +1,4 @@ --- title: Programmatic access -weight: 8 +weight: 6 --- diff --git a/content/api/cli.md b/content/reference/programmatic-access/cli.md similarity index 77% rename from content/api/cli.md rename to content/reference/programmatic-access/cli.md index 8acb8beb..9145ad70 100644 --- a/content/api/cli.md +++ b/content/reference/programmatic-access/cli.md @@ -28,11 +28,11 @@ In these commands: ## Validating declarations -{{< refItem name="ota validate [--services ...] [--types ...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="npx ota validate --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}} +{{< refItem name="ota validate declarations [--services ...] [--types ...]" description="Check that all declarations allow recording a snapshot and a version properly. If service IDs are provided, check only those services." example="npx ota validate declarations --services \"Facebook\" --types \"Privacy Policy\"" />}} -{{< refItem name="ota validate --schema-only [--services ...] [--types ...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="npx ota validate --schema-only --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"" />}} +{{< refItem name="ota validate declarations --schema-only [--services ...] [--types ...]" description="Check that all declarations are readable by the engine. Allows for a much faster check of declarations, but does not check that the terms are actually accessible." example="npx ota validate declarations --schema-only --services \"Facebook\" --types \"Privacy Policy\"" />}} -{{< refItem name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="npx ota validate --modified" />}} +{{< refItem name="ota validate declarations --modified" description="Run ota validate only on files that have been modified in Git" example="npx ota validate declarations --modified" />}} ## Linting declarations @@ -42,6 +42,10 @@ In these commands: {{< refItem name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="npx ota lint --modified" />}} +## Validating metadata file + +{{< refItem name="ota validate metadata" description="Check that the metadata file structure is valid" example="npx ota validate metadata" />}} + ## Publishing dataset {{< refItem name="ota dataset [--file ]" description="Export the versions dataset into a ZIP file and publish it to GitHub releases. The dataset title and the URL of the versions repository are defined in the configuration." example="npx ota dataset --file dataset.zip" />}} @@ -50,7 +54,7 @@ To export the dataset into a ZIP file and publish it on GitHub releases: {{< refItem name="ota dataset --publish [--file ]" description="Export and publish dataset to GitHub releases" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish" />}} -The `GITHUB_TOKEN` can also be defined in a [`.env` file]({{< relref "collections/reference/environment-variables" >}}). +The `GITHUB_TOKEN` can also be defined in a `.env` file. To export, publish the dataset and remove the local copy that was created after it has been uploaded: diff --git a/content/api/collection.md b/content/reference/programmatic-access/collection-api.md similarity index 100% rename from content/api/collection.md rename to content/reference/programmatic-access/collection-api.md diff --git a/content/api/federation.md b/content/reference/programmatic-access/federation-api.md similarity index 100% rename from content/api/federation.md rename to content/reference/programmatic-access/federation-api.md diff --git a/content/reference/programmatic-access/node-module.md b/content/reference/programmatic-access/node-module.md new file mode 100644 index 00000000..84004a67 --- /dev/null +++ b/content/reference/programmatic-access/node-module.md @@ -0,0 +1,93 @@ +--- +title: Node.js module +weight: 1 +--- + +# Node.js module + +As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code. + + + +#### Classes + +* [SourceDocument](#SourceDocument) + * [`new SourceDocument(params)`](#new_SourceDocument_new) + +#### Functions + +* [`extract(sourceDocument)`](#extract) ⇒ Promise.<string> +* [`launchHeadlessBrowser()`](#launchHeadlessBrowser) ⇒ Promise.<puppeteer.Browser> +* [`stopHeadlessBrowser()`](#stopHeadlessBrowser) ⇒ Promise.<void> +* [`fetch(params)`](#fetch) ⇒ Promise.<{mimeType: string, content: (string\|Buffer)}> + +--- + + + +#### SourceDocument +**Kind**: global class + + +##### `new SourceDocument(params)` +Represents a source document containing web content and metadata for extraction. +Includes the document location, selectors for content inclusion/exclusion, +content filters, raw content data, and MIME type information. + + +| Param | Type | Description | +| --- | --- | --- | +| params | object | The source document parameters | +| params.location | string | The URL location of the document | +| params.executeClientScripts | boolean | Whether to execute client-side scripts | +| params.contentSelectors | string \| object \| Array | CSS selectors for content to include | +| params.insignificantContentSelectors | string \| object \| Array | CSS selectors for content to exclude | +| params.filters | Array | Array of filters to apply | +| params.content | string | The document content | +| params.mimeType | string | The MIME type of the content | + + + +#### `extract(sourceDocument)` ⇒ Promise.<string> +Extract content from source document and convert it to Markdown + +**Kind**: global function +**Returns**: Promise.<string> - Promise which is fulfilled once the content is extracted and converted in Markdown. The promise will resolve into a string containing the extracted content in Markdown format + +| Param | Type | Description | +| --- | --- | --- | +| sourceDocument | string | Source document from which to extract content, see [SourceDocument](#SourceDocument) | + + + +#### `launchHeadlessBrowser()` ⇒ Promise.<puppeteer.Browser> +Launches a headless browser instance using Puppeteer if one is not already running. Returns the existing browser instance if one is already running, otherwise creates and returns a new instance. + +**Kind**: global function +**Returns**: Promise.<puppeteer.Browser> - The Puppeteer browser instance. + + +#### `stopHeadlessBrowser()` ⇒ Promise.<void> +Stops the headless browser instance if one is running. If no instance exists, it does nothing. + +**Kind**: global function + + +#### `fetch(params)` ⇒ Promise.<{mimeType: string, content: (string\|Buffer)}> +Fetch a resource from the network, returning a promise which is fulfilled once the response is available + +**Kind**: global function +**Returns**: Promise.<{mimeType: string, content: (string\|Buffer)}> - Promise containing the fetched resource's MIME type and content + +| Param | Type | Description | +| --- | --- | --- | +| params | object | Fetcher parameters | +| params.url | string | URL of the resource you want to fetch | +| [params.executeClientScripts] | boolean | Enable execution of client scripts. When set to `true`, this property loads the page in a headless browser to load all assets and execute client scripts before returning its content | +| [params.cssSelectors] | string \| Array | List of CSS selectors to await when loading the resource in a headless browser. Can be a CSS selector or an array of CSS selectors. Only relevant when `executeClientScripts` is enabled | +| [params.config] | object | Fetcher configuration | +| [params.config.navigationTimeout] | number | Maximum time (in milliseconds) to wait before considering the fetch failed | +| [params.config.language] | string | Language (in [ISO 639-1 format](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)) to be passed in request headers | +| [params.config.waitForElementsTimeout] | number | Maximum time (in milliseconds) to wait for selectors to exist on page before considering the fetch failed. Only relevant when `executeClientScripts` is enabled | + + diff --git a/content/terms/_index.md b/content/reference/terms/_index.md similarity index 54% rename from content/terms/_index.md rename to content/reference/terms/_index.md index 420599f2..29cd039b 100644 --- a/content/terms/_index.md +++ b/content/reference/terms/_index.md @@ -1,4 +1,4 @@ --- -title: "Terms" +title: Terms weight: 4 --- diff --git a/content/terms/guideline/choosing-selectors.md b/content/reference/terms/choosing-selectors.md similarity index 85% rename from content/terms/guideline/choosing-selectors.md rename to content/reference/terms/choosing-selectors.md index 194e45b9..228ee376 100644 --- a/content/terms/guideline/choosing-selectors.md +++ b/content/reference/terms/choosing-selectors.md @@ -11,9 +11,9 @@ Selectors are used in Open Terms Archive declarations to specify the parts of ## What are selectors -Selectors are used in the [`select`]({{< relref "terms/reference#select" >}}) and [`remove`]({{< relref "terms/reference#remove" >}}) keys of an Open Terms Archive declaration. +Selectors are used in the [`select`]({{< relref "/how-to/tracking/track-new-terms#select" >}}) and [`remove`]({{< relref "/how-to/tracking/track-new-terms#remove" >}}) keys of an Open Terms Archive declaration. -The “selectors” referred to are defined by the [W3C Selectors standard](https://www.w3.org/TR/selectors/), more commonly known as “CSS Selectors”. +The "selectors" referred to are defined by the [W3C Selectors standard](https://www.w3.org/TR/selectors/), more commonly known as "CSS Selectors". An easy-to-read introduction to CSS Selectors can be found on [mdn web docs](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors). @@ -166,7 +166,7 @@ If in doubt about a selector, prefer making a wide selection and then removing t ### Use range selectors -[Range selectors]({{< relref "terms/reference#range-selectors" >}}) enable to select content that starts in one block and ends in another block that are not in the same tree. While they are more complex than element selectors, it is preferable to use a range selector whose start and end abide by the guidelines above than to use a bad plain selector. +[Range selectors]({{< relref "/how-to/tracking/track-new-terms#range-selectors" >}}) enable to select content that starts in one block and ends in another block that are not in the same tree. While they are more complex than element selectors, it is preferable to use a range selector whose start and end abide by the guidelines above than to use a bad plain selector. #### Example @@ -219,6 +219,6 @@ For the following HTML code: {{< /details >}} -### “Good enough” +### "Good enough" -Do not spend too much time trying to find the perfect selectors. Reviewers, in particular, will often have to conclude to “good enough” where their preference or the other authors are equally valid, since assumptions are made about the website DOM structure and how it may change in the future. It is more important to regularly review versions and react quickly to correct selectors than to find the perfect ones up front. +Do not spend too much time trying to find the perfect selectors. Reviewers, in particular, will often have to conclude to "good enough" where their preference or the other authors are equally valid, since assumptions are made about the website DOM structure and how it may change in the future. It is more important to regularly review versions and react quickly to correct selectors than to find the perfect ones up front. diff --git a/content/terms/reference/filters.md b/content/reference/terms/filters.md similarity index 96% rename from content/terms/reference/filters.md rename to content/reference/terms/filters.md index 6006c8a0..9d1e649e 100644 --- a/content/terms/reference/filters.md +++ b/content/reference/terms/filters.md @@ -25,7 +25,7 @@ Each filter is exposed as a named function export that takes a `document` parame > The `document` parameter is actually a [JSDOM](https://github.com/jsdom/jsdom) document instance. -You can learn more about usual noise and ways to handle it [in the guidelines]({{< relref "/terms/guideline/declaring#usual-noise" >}}). +You can learn more about usual noise and ways to handle it in the guidelines. ### Example diff --git a/content/terms/reference/declaration.md b/content/reference/terms/service-declaration.md similarity index 99% rename from content/terms/reference/declaration.md rename to content/reference/terms/service-declaration.md index 454d895d..ed174cfd 100644 --- a/content/terms/reference/declaration.md +++ b/content/reference/terms/service-declaration.md @@ -140,7 +140,7 @@ As an array of those: {{< refItem name="filter" type="array of strings" - description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"terms/reference/filters\" >}}) section for more information." + description="Array of filter function names to apply. Function will be executed in the order of the array. See the [Filters]({{< relref \"reference/terms/filters\" >}}) section for more information." example="[\"filterName1\", \"filterName2\"]" />}} diff --git a/content/reference/terms/service-naming.md b/content/reference/terms/service-naming.md new file mode 100644 index 00000000..8ce1b497 --- /dev/null +++ b/content/reference/terms/service-naming.md @@ -0,0 +1,6 @@ +--- +title: Service naming conventions +weight: 5 +--- + +# Service naming diff --git a/content/terms/guideline/targeting.md b/content/terms/guideline/targeting.md deleted file mode 100644 index 545ee7c6..00000000 --- a/content/terms/guideline/targeting.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: "Targeting" -aliases: - - /terms/guidelines/targeting/ ---- - -# What to track? - -## Can I track terms that are not applicable yet? - -Yes. - -For example, terms that would start applying at date in the future are legitimate candidates for tracking. You can this way track if their terms change even before they are applied. diff --git a/content/terms/how-to/_index.md b/content/terms/how-to/_index.md deleted file mode 100644 index d6db9c3c..00000000 --- a/content/terms/how-to/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: How to guides -weight: 2 ---- diff --git a/content/terms/how-to/declarations-maintenance-inspector-open-get-datetime.png b/content/terms/how-to/declarations-maintenance-inspector-open-get-datetime.png deleted file mode 100644 index 5d32ce24..00000000 Binary files a/content/terms/how-to/declarations-maintenance-inspector-open-get-datetime.png and /dev/null differ diff --git a/content/terms/how-to/declarations-maintenance-ota-bot-comment-last-month.png b/content/terms/how-to/declarations-maintenance-ota-bot-comment-last-month.png deleted file mode 100644 index b64b3f19..00000000 Binary files a/content/terms/how-to/declarations-maintenance-ota-bot-comment-last-month.png and /dev/null differ diff --git a/content/terms/how-to/declarations-maintenance-ota-bot-comment-reopened-issue.png b/content/terms/how-to/declarations-maintenance-ota-bot-comment-reopened-issue.png deleted file mode 100644 index 8ba1c95f..00000000 Binary files a/content/terms/how-to/declarations-maintenance-ota-bot-comment-reopened-issue.png and /dev/null differ diff --git a/content/terms/how-to/declarations-maintenance-ota-bot-comment.png b/content/terms/how-to/declarations-maintenance-ota-bot-comment.png deleted file mode 100644 index 351845e9..00000000 Binary files a/content/terms/how-to/declarations-maintenance-ota-bot-comment.png and /dev/null differ diff --git a/content/terms/how-to/rename-a-service.md b/content/terms/how-to/rename-a-service.md deleted file mode 100644 index 9b091b5f..00000000 --- a/content/terms/how-to/rename-a-service.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: How to rename a service -linkTitle: Rename a service -weight: 5 ---- - -# How to rename a service - -The consensus is to consider that a service provider renaming a service (for example, `Twitter` to `X`) is akin to terminating the previous service and opening a new one. Therefore, to apply a service renaming, open a pull request that both [terminates the previous service](#how-to-terminate-a-service) and adds a new [service declaration]({{< relref "terms/how-to/track-terms#declaring-a-new-service" >}}) with the new service name. You can reuse the `terms` part of the original declaration, but should double-check that the selectors and URLs still match, as a service rename is most often accompanied by a new page layout, a new domain name, and sometimes entirely new terms. diff --git a/content/terms/reference/_index.md b/content/terms/reference/_index.md deleted file mode 100644 index fd021bb8..00000000 --- a/content/terms/reference/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: References -weight: 3 ---- diff --git a/content/terms/tutorial/_index.md b/content/terms/tutorial/_index.md deleted file mode 100644 index 18583df4..00000000 --- a/content/terms/tutorial/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Tutorials -weight: 1 ---- diff --git a/content/collections/tutorial/_index.md b/content/tutorials/_index.md similarity index 100% rename from content/collections/tutorial/_index.md rename to content/tutorials/_index.md diff --git a/content/tutorials/create-collection copy.md b/content/tutorials/create-collection copy.md new file mode 100644 index 00000000..9eb1b563 --- /dev/null +++ b/content/tutorials/create-collection copy.md @@ -0,0 +1,6 @@ +--- +title: Track your first terms +weight: 1 +--- + +# Create your first collection diff --git a/content/collections/tutorial/create.md b/content/tutorials/create-collection.md similarity index 94% rename from content/collections/tutorial/create.md rename to content/tutorials/create-collection.md index aacd5ecd..8db9d31a 100644 --- a/content/collections/tutorial/create.md +++ b/content/tutorials/create-collection.md @@ -1,11 +1,7 @@ --- title: Create your first collection -weight: 1 -aliases: - - /collections/create/ - - /collections/tutorials/create/ +weight: 2 --- - # Create your first collection This tutorial will guide you through creating your first Open Terms Archive collection. @@ -40,7 +36,7 @@ By the end, you'll have a working collection that tracks changes to a service's ### Step 2: Create the service declaration -4. Create a file `declarations/Open Terms Archive.json` with the following content. For detailed instructions on how to structure it, follow the [Tracking terms tutorial]({{< relref "/terms/tutorial/track" >}}): +4. Create a file `declarations/Open Terms Archive.json` with the following content. For detailed instructions on how to structure it, follow the [Tracking terms tutorial]({{< relref "/how-to/tracking/track-new-terms" >}}): ```json { "name": "Open Terms Archive", diff --git a/package.json b/package.json index 4bf0450c..7c947b84 100644 --- a/package.json +++ b/package.json @@ -21,7 +21,7 @@ "lint:css": "stylelint \"themes/opentermsarchive/assets/css/*.css\"", "lint:js": "eslint themes/opentermsarchive/assets/js/", "start:dev": "npm run jsdoc && hugo serve --watch --logLevel debug --disableFastRender --ignoreCache", - "jsdoc": "jsdoc2md --files './node_modules/@opentermsarchive/engine/src/**/*.js' --template scripts/jsdoc/template/node.hbs -g grouped --name-format -d 4 > content/api/node.md" + "jsdoc": "jsdoc2md --files './node_modules/@opentermsarchive/engine/src/**/*.js' --template scripts/jsdoc/template/node.hbs -g grouped --name-format -d 4 > content/reference/programmatic-access/node-module.md" }, "devDependencies": { "eslint": "^8.31.0", diff --git a/themes/opentermsarchive/assets/css/base.css b/themes/opentermsarchive/assets/css/base.css index 89fb8958..e5aa87e7 100644 --- a/themes/opentermsarchive/assets/css/base.css +++ b/themes/opentermsarchive/assets/css/base.css @@ -10,11 +10,11 @@ html { } body { - background-color: var(--colorWhite); font-family: var(--defaultFontFamily); font-size: var(--defaultFontSize); + font-weight: normal; + line-height: 1.6; color: var(--colorBlack900); - line-height: 1.5; letter-spacing: -0.2px; - font-weight: normal; + background-color: var(--colorWhite); } diff --git a/themes/opentermsarchive/assets/css/components/aside.css b/themes/opentermsarchive/assets/css/components/aside.css index cc305d3e..973d4d85 100644 --- a/themes/opentermsarchive/assets/css/components/aside.css +++ b/themes/opentermsarchive/assets/css/components/aside.css @@ -2,8 +2,6 @@ flex-shrink: 0; margin-right: var(--mXL); @mixin grid 3, 2; - border: 1px solid var(--colorBlack200); - border-radius: 4px; } @media (--tabletSmall) { @@ -14,157 +12,118 @@ } .aside_nav { - > ul > li > details > ul > li:last-child, - > ul > li > details > ul > li:not(:last-child) > ul { - margin-bottom: var(--mS); + + & a{ + color: var(--colorBlack800); + z-index:1; + position:relative; + display:block; + + &:hover{ + &:before{ + content:""; + position:absolute; + left:calc(var(--xs) * -1); + right:0; + top:calc(var(--3xs) * -1); + bottom:calc(var(--3xs) * -1); + width:calc(100% + var(--xs)); + height:calc(100% + var(--2xs)); + z-index:-1; + background-color: var(--colorBlack200); + } + } + } + + & .aside_item-current{ + font-weight: bold; + + & a{ + color: var(--colorPrimary); + } } ul { - color: var(--colorBlack600); + color: var(--colorBlack800); display: flex; + gap:var(--m3XS); flex-direction: column; li { - position: relative; - border-bottom: 1px solid var(--colorBlack200); - - &:last-child { - border: none; - } - - a { - padding: var(--mXS) var(--mS); - display: inline-block; - width: 100%; - } - - .aside_item-current { - color: var(--colorBlack800); - - &::before { - content: ''; - position: absolute; - left: 0; - width: 4px; - background-color: var(--colorPrimary); - border-radius: 0 10px 10px 0; - z-index: 1; - top: var(--m2XS); - bottom: var(--m2XS); - } - - &::after { - content: ''; - position: absolute; - background-color: var(--colorBlack200); - border-radius: 4px; - z-index: -1; - left: var(--mXS); - right: var(--m2XS); - top: var(--m2XS); - bottom: var(--m2XS); - } - } - - &.aside_item-current-section { - &::before { - content: ''; - position: absolute; - left: 0; - top: 0; - bottom: 0; - width: 1px; - background-color: var(--colorPrimary); - border-radius: 0; - } - - & .aside_item-current { - &::before { - top: 2px; - bottom: 2px; - } - - &::after { - top: 0; - bottom: 0; - right: var(--mXS); + margin-top: 4px; + & ul { + & li { + & ul { + margin-top:var(--2xs); + border-left:1px solid var(--colorBlack300); + padding-left:0.8em; + margin-left: -0.8em; } } } + } + } - details { - position: relative; - - summary { - padding: var(--mXS) var(--mS); - list-style: none; - cursor: pointer; - - &::marker, - &::-webkit-details-marker { - display: none; - } - - & svg { - position: absolute; - right: 10px; - top: 14px; - font-size: 0.8em; - color: var(--colorBlack400); - transition: transform 0.2s ease; - } - - &:hover::after { - content: ''; - position: absolute; - inset: 0; - background-color: var(--colorBlack100); - z-index: -1; - } - } - - &[open] summary > svg { - transform: rotate(180deg); + details{ + &[open]{ + & summary{ + > svg { + transform: rotate(0deg); } } - - span { - display: inline-block; - } } + } - ul { - li { - border: none; - - a { - padding: var(--p3XS) var(--mL); - border-radius: 4px; - } + summary{ + display:flex; + align-items:center; + gap:var(--2xs); + cursor:pointer; + color: var(--colorBlack800); + margin-top: 0; + + &::marker, + &::-webkit-details-marker { + display: none; + } - > span, - a { - padding-left: var(--mS); - } + & .icon{ + margin-top:var(--3xs); + } + position: relative; + + & svg { + transform: rotate(-90deg); + color: var(--colorBlack400); + font-size:0.8em; + transition: transform 0.2s ease; + position:absolute; + left: -1.5em; + } + } - > a { - padding-top: var(--p3XS); - padding-bottom: var(--p3XS); - } + .aside_item-subsection-count{ + background-color: var(--colorBlack200); + padding: 0em 0.5em; + border-radius: 1em; + font-size:0.60em; + color: var(--colorBlack700); + /* display:none; */ + display:none; + vertical-align: middle; - ul { - padding-top: 0; + } +} - li { - padding: 0; +.aside_item-section{ + display:inline-block; + margin-top:var(--m); + color: var(--colorBlack800); + font-weight: bold; +} - a { - padding: var(--p3XS) var(--mL); - border-radius: 4px; - } - } - } - } - } - } +.aside_item-subsection{ + display:inline-block; + margin-top:var(--m2XS); + color: var(--colorBlack800); } diff --git a/themes/opentermsarchive/assets/css/components/textContent.css b/themes/opentermsarchive/assets/css/components/textContent.css index 58cc7ab7..b8bd68c1 100644 --- a/themes/opentermsarchive/assets/css/components/textContent.css +++ b/themes/opentermsarchive/assets/css/components/textContent.css @@ -1,6 +1,6 @@ .textContent { border:1Px solid var(--colorBlack200); - padding:var(--mL); + padding:var(--pL); overflow-x: hidden; max-width: 100%; width: 100%; diff --git a/themes/opentermsarchive/assets/css/custom-properties.css b/themes/opentermsarchive/assets/css/custom-properties.css index 344486fc..d04be9a7 100644 --- a/themes/opentermsarchive/assets/css/custom-properties.css +++ b/themes/opentermsarchive/assets/css/custom-properties.css @@ -13,15 +13,16 @@ --gridGutterWidth: 24px; /* Colors */ - --colorPrimary: #0496ff; + --colorPrimary: #2d63ff; + --colorPrimary300: #c5d9ff; --colorSecondary: #0b08a0; --colorTertiary: #f9dd3f; - --colorDarkedSecondary: #b4656f; --colorError: #ec368d; --colorSuccess: #11ebc3; --colorBlack900: #010613; --colorBlack850: #171717; --colorBlack800: #333; + --colorBlack700: #454545; --colorBlack600: #5e5e5e; --colorBlack400: #999; --colorBlack300: #d6d6d6; @@ -29,27 +30,39 @@ --colorBlack100: #fafafa; --colorWhite: #fefffd; + /* Sizes */ + --3xs: 2px; + --2xs: 4px; + --xs: 8px; + --s: 12px; + --m: 16px; + --l: 24px; + --xl: 36px; + --2xl: 48px; + --3xl: 64px; + --4xl: 96px; + /* Padding & margin */ - --p3XS: 2px; - --p2XS: 4px; - --pXS: 8px; - --pS: 12px; - --pM: 16px; - --pL: 24px; - --pXL: 36px; - --p2XL: 48px; - --p3XL: 64px; - --p4XL: 96px; - --m3XS: 2px; - --m2XS: 4px; - --mXS: 8px; - --mS: 12px; - --mM: 16px; - --mL: 24px; - --mXL: 36px; - --m2XL: 48px; - --m3XL: 64px; - --m4XL: 96px; + --p3XS: var(--3xs); + --p2XS: var(--2xs); + --pXS: var(--xs); + --pS: var(--s); + --pM: var(--m); + --pL: var(--l); + --pXL: var(--xl); + --p2XL: var(--2xl); + --p3XL: var(--3xl); + --p4XL: var(--4xl); + --m3XS: var(--3xs); + --m2XS: var(--2xs); + --mXS: var(--xs); + --mS: var(--s); + --mM: var(--m); + --mL: var(--l); + --mXL: var(--xl); + --m2XL: var(--2xl); + --m3XL: var(--3xl); + --m4XL: var(--4xl); /* Breakpoints */ --bpMobileSmall: 320px; diff --git a/themes/opentermsarchive/assets/css/elements/links.css b/themes/opentermsarchive/assets/css/elements/links.css index 9c81fc21..ab7f3482 100644 --- a/themes/opentermsarchive/assets/css/elements/links.css +++ b/themes/opentermsarchive/assets/css/elements/links.css @@ -7,6 +7,10 @@ a { color: var(--colorSecondary); transition: all 0.25s easeoutcirc; } + + &:active { + color: var(--colorSecondary); + } } .a--small { diff --git a/themes/opentermsarchive/layouts/partials/aside.html b/themes/opentermsarchive/layouts/partials/aside.html index c4dd6ae0..7bfa4ed1 100644 --- a/themes/opentermsarchive/layouts/partials/aside.html +++ b/themes/opentermsarchive/layouts/partials/aside.html @@ -1,37 +1,40 @@ -