Merge branch 'main' into all-contributors/add-zenobioarn

Author: MattiSG

.all-contributors.md

@@ -19,6 +19,7 @@ This file is required by [All Contributors](https://allcontributors.org/) to wor
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/Aysha-py"><img src="https://avatars.githubusercontent.com/u/64032658?v=4?s=100" width="100px;" alt="Aysha Muhammed"/><br /><sub><b>Aysha Muhammed</b></sub></a><br /><a href="https://github.com/OpenTermsArchive/docs/commits?author=Aysha-py" title="Documentation">📖</a> <a href="#promotion-Aysha-py" title="Promotion">📣</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/margelacool"><img src="https://avatars.githubusercontent.com/u/74462536?v=4?s=100" width="100px;" alt="margelacool "/><br /><sub><b>margelacool </b></sub></a><br /><a href="#ideas-margelacool" title="Ideas, Planning, & Feedback">🤔</a></td>
       <td align="center" valign="top" width="14.28%"><a href="https://github.com/zenobioarn"><img src="https://avatars.githubusercontent.com/u/189729038?v=4?s=100" width="100px;" alt="Zenobio de Almeida"/><br /><sub><b>Zenobio de Almeida</b></sub></a><br /><a href="#ideas-zenobioarn" title="Ideas, Planning, & Feedback">🤔</a></td>
+      <td align="center" valign="top" width="14.28%"><a href="https://kcode.de/"><img src="https://avatars.githubusercontent.com/u/93181?v=4?s=100" width="100px;" alt="Jan Klass"/><br /><sub><b>Jan Klass</b></sub></a><br /><a href="https://github.com/OpenTermsArchive/docs/commits?author=Kissaki" title="Documentation">📖</a></td>
     </tr>
   </tbody>
 </table>

.all-contributorsrc

@@ -108,6 +108,15 @@
       "contributions": [
         "ideas"
       ]
+    },
+    {
+      "login": "Kissaki",
+      "name": "Jan Klass",
+      "avatar_url": "https://avatars.githubusercontent.com/u/93181?v=4",
+      "profile": "https://kcode.de/",
+      "contributions": [
+        "doc"
+      ]
     }
   ],
   "repoType": "github",

CODE_OF_CONDUCT.md

@@ -6,15 +6,15 @@ We as members, contributors, and leaders pledge to make participation in our
 community a harassment-free experience for everyone, regardless of age, body
 size, visible or invisible disability, ethnicity, sex characteristics, gender
 identity and expression, level of experience, education, socio-economic status,
-nationality, personal appearance, race, caste, color, religion, or sexual
+nationality, personal appearance, race, caste, colour, religion, or sexual
 identity and orientation.
 
 We pledge to act and interact in ways that contribute to an open, welcoming,
 diverse, inclusive, and healthy community.
 
 ## Our Standards
 
-Examples of behavior that contributes to a positive environment for our
+Examples of behaviour that contributes to a positive environment for our
 community include:
 
 - Demonstrating empathy and kindness toward other people
@@ -25,7 +25,7 @@ community include:
 - Focusing on what is best not just for us as individuals, but for the overall
   community
 
-Examples of unacceptable behavior include:
+Examples of unacceptable behaviour include:
 
 - The use of sexualized language or imagery, and sexual attention or advances of
   any kind
@@ -39,8 +39,8 @@ Examples of unacceptable behavior include:
 ## Enforcement Responsibilities
 
 Community leaders are responsible for clarifying and enforcing our standards of
-acceptable behavior and will take appropriate and fair corrective action in
-response to any behavior that they deem inappropriate, threatening, offensive,
+acceptable behaviour and will take appropriate and fair corrective action in
+response to any behaviour that they deem inappropriate, threatening, offensive,
 or harmful.
 
 Community leaders have the right and responsibility to remove, edit, or reject
@@ -58,7 +58,7 @@ representative at an online or offline event.
 
 ## Enforcement
 
-Instances of abusive, harassing, or otherwise unacceptable behavior may be
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
 reported to the community leaders responsible for enforcement at
 `[email protected]`.
 All complaints will be reviewed and investigated promptly and fairly.
@@ -73,19 +73,19 @@ the consequences for any action they deem in violation of this Code of Conduct:
 
 ### 1. Correction
 
-**Community Impact**: Use of inappropriate language or other behavior deemed
+**Community Impact**: Use of inappropriate language or other behaviour deemed
 unprofessional or unwelcome in the community.
 
 **Consequence**: A private, written warning from community leaders, providing
 clarity around the nature of the violation and an explanation of why the
-behavior was inappropriate. A public apology may be requested.
+behaviour was inappropriate. A public apology may be requested.
 
 ### 2. Warning
 
 **Community Impact**: A violation through a single incident or series of
 actions.
 
-**Consequence**: A warning with consequences for continued behavior. No
+**Consequence**: A warning with consequences for continued behaviour. No
 interaction with the people involved, including unsolicited interaction with
 those enforcing the Code of Conduct, for a specified period of time. This
 includes avoiding interactions in community spaces as well as external channels
@@ -95,7 +95,7 @@ ban.
 ### 3. Temporary Ban
 
 **Community Impact**: A serious violation of community standards, including
-sustained inappropriate behavior.
+sustained inappropriate behaviour.
 
 **Consequence**: A temporary ban from any sort of interaction or public
 communication with the community for a specified period of time. No public or
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
 ### 4. Permanent Ban
 
 **Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
+standards, including sustained inappropriate behaviour, harassment of an
 individual, or aggression toward or disparagement of classes of individuals.
 
 **Consequence**: A permanent ban from any sort of public interaction within the

CONTRIBUTING.md

@@ -1,24 +1,71 @@
-# Contributing to this repository
+# Contributing to the Open Terms Archive documentation
 
-## 🚀 How to Contribute
+First of all, thanks for taking the time to contribute! 🎉👍
 
-- You can check the open issues in this repository, comment to state your interest and solve them.
-- You can also open issues to suggest additions or changes to this documentation website.
+## Code of Conduct
 
-## 📜 Read our Code of Conduct
+Before you begin coding and collaborating, please read our [Code of Conduct](./CODE_OF_CONDUCT.md) to understand the standards for interacting in this community. As a participant and contributor to this project, you agree to abide by our Code of Conduct.
 
-Before you begin coding and collaborating, please read our [Code of Conduct](./CODE_OF_CONDUCT.md) to understand the standards (that you are required to adhere to) for community engagement. As part of our open-source community, we hold ourselves and other contributors to a high standard of communication. As a participant and contributor to this project, you are agreeing to abide by our Code of Conduct.
+## Architecture
 
-## 💻 Need Help?
+This documentation follows the [Diátaxis](https://diataxis.fr) approach and structures content in different categories:
 
-We are more than happy to help you. If you are facing problems while working on any issue, don’t hesitate to ask for help.
+- **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.
 
-Your contribution, no matter its size, holds immense value. We eagerly await to see the impact you'll make in our community! 🚀
+## Copywriting
 
-## List a new contributor in the Open Terms Archive website
+- Use [British English spelling](https://en.wikipedia.org/wiki/American_and_British_English_spelling_differences), not American English.
 
-We acknowledge the efforts of our contributors by listing them on our [website](https://opentermsarchive.org) and this is made possible by the use of the [All Contributors bot](https://allcontributors.org/docs/en/bot/overview).
+## Modifying content
 
-All Contributors enables adding a contributor with a comment on an issue or pull request, without writing code. To do this, please use the [dedicated issue](https://github.com/OpenTermsArchive/docs/issues/134) on this repository.
+Start by identifying the page you would like to add the content to by [navigating the documentation](https://docs.opentermsarchive.org). Once you have found the best location, find the [associated source document](https://github.com/OpenTermsArchive/docs/tree/main/content) and edit it. If there is no existing best location, think of the page where you would like to find it and create that page by clicking “Add file” in the [source folder](https://github.com/OpenTermsArchive/docs/tree/main/content).
+
+## Workflow
+
+### Pull requests
+
+We follow the [GitHub Flow](https://guides.github.com/introduction/flow/): all contributions are submitted via a pull request towards the `main` branch.
+
+Opening a pull request means you want that code to be merged. If you want to only discuss it, send a link to your branch along with your questions through whichever communication channel you prefer.
+
+#### Peer reviews
+
+All pull requests must be reviewed by at least one person who is not their original author.
+
+To help reviewers, make sure to describe your pull request with a **clear text explanation** of your changes.
+
+For pull requests of new contributors, if errors or areas for improvement are identified in their contributions, the Open Terms Archive team can initially handle them. This is intended to speed up the delivery process and help the contributor acclimatise to the project. As they become more involved and learn more, they will be encouraged to take on more responsibility by implementing the changes themselves. The aim is to support growth and confidence in the contribution to the project while promoting quick delivery.
+
+### Continuous delivery
+
+GitHub Actions is used to publish the documentation on every merge to the main branch.
 
-Please read the following [contributing guide](https://github.com/OpenTermsArchive/opentermsarchive.org/blob/main/CONTRIBUTING.md#list-a-new-contributor-in-the-open-terms-archive-website).
+Branch protection is active, meaning that a merge to the main branch can only take place once all tests pass in CI, and that the peer review policy has been fulfilled.
+
+### Commit messages
+
+We strive to follow this [recommendation](https://chris.beams.io/posts/git-commit) to write our commit messages, which contains the following rules:
+
+- [Separate subject from body with a blank line](https://chris.beams.io/posts/git-commit/#separate).
+- [Limit the subject line to 50 characters](https://chris.beams.io/posts/git-commit/#limit-50).
+- [Capitalize the subject line](https://chris.beams.io/posts/git-commit/#capitalize).
+- [Do not end the subject line with a period](https://chris.beams.io/posts/git-commit/#end).
+- [Use the imperative mood in the subject line](https://chris.beams.io/posts/git-commit/#imperative).
+- [Use the body to explain what and why vs. how](https://chris.beams.io/posts/git-commit/#why-not-how).
+
+Except this one:
+
+- ~~[Wrap the body at 72 characters](https://chris.beams.io/posts/git-commit/#wrap-72)~~: As URLs might be used for references in commit messages, the body text is not wrapped to 72 characters to ensure links are clickable in Git user interfaces.
+
+We add these additional rules:
+
+- Do not rely on GitHub issue reference numbers in commit messages, as we have no guarantee the host system and its autolinking will be stable in time. Make sure the context is self-explanatory. If an external reference is given, use its full URL.
+
+## List contributors in the Open Terms Archive website
+
+We acknowledge the efforts of our contributors by listing them on our [website](https://opentermsarchive.org) through [All Contributors](https://allcontributors.org/docs/en/bot/overview).
+
+All Contributors enables adding a contributor with a comment on an issue or pull request, without writing code. To do this, please use the [dedicated issue](https://github.com/OpenTermsArchive/docs/issues/134) on this repository.

content/_index.md

@@ -29,7 +29,7 @@ This documentation follows the [Diátaxis](https://diataxis.fr) approach and str
 
 ### 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.
+- **Analysis:** guidance on how to analyse 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.

content/analysis/how-to/navigate-history.md

@@ -40,7 +40,7 @@ For this guide, we will use the example of the Demo collection. The terms of thi
 
   ![One GitHub Privacy Policy change with source diff view](/images/navigate-history/source-diff.png)
 
-- You can choose from two types of display with the icons in the grey bar above the document. The first one (which is also the default one), named _source diff_ displays the previous version and the next one either [side by side](https://github.com/OpenTermsArchive/demo-versions/commit/e9a781797041a6b593967ba9e7bb2c7404390e76?diff=split) or in a [consolidated way (with one line under the other)](https://github.com/OpenTermsArchive/demo-versions/commit/e9a781797041a6b593967ba9e7bb2c7404390e76?diff=unified). The second one, named _rich diff_ displays all the changes [in a single document](https://github.com/OpenTermsArchive/demo-versions/commit/e9a781797041a6b593967ba9e7bb2c7404390e76?short_path=060f2c2#diff-060f2c2cc43c2415e0d388f0061c37472277e76eafc9c0df269713b150a52909). In this view, beyond green and red, the yellow color shows modified paragraphs. Be careful, this display does not show some changes such as hyperlinks and text style's changes:
+- You can choose from two types of display with the icons in the grey bar above the document. The first one (which is also the default one), named _source diff_ displays the previous version and the next one either [side by side](https://github.com/OpenTermsArchive/demo-versions/commit/e9a781797041a6b593967ba9e7bb2c7404390e76?diff=split) or in a [consolidated way (with one line under the other)](https://github.com/OpenTermsArchive/demo-versions/commit/e9a781797041a6b593967ba9e7bb2c7404390e76?diff=unified). The second one, named _rich diff_ displays all the changes [in a single document](https://github.com/OpenTermsArchive/demo-versions/commit/e9a781797041a6b593967ba9e7bb2c7404390e76?short_path=060f2c2#diff-060f2c2cc43c2415e0d388f0061c37472277e76eafc9c0df269713b150a52909). In this view, beyond green and red, the yellow colour shows modified paragraphs. Be careful, this display does not show some changes such as hyperlinks and text style's changes:
 
   ![One GitHub Privacy Policy change with rich diff view](/images/navigate-history/rich-diff.png)
 

content/collections/explanation/_index.md

@@ -0,0 +1,4 @@
+---
+title: Explanations
+weight: 4
+---

content/collections/explanation/reporting.md

@@ -0,0 +1,32 @@
+---
+title: Reporting
+weight: 1
+---
+
+# Reporting
+
+Once services are declared in a collection and this collection starts tracking these terms, it becomes crucial to monitor whether the tracking is functioning properly. It is important to know if there are any terms whose tracking has been interrupted or has failed.
+
+## How the reporting system works
+
+To address this need, the Open Terms Archive engine implements an automated reporting system that creates issues in the declarations repository. This system helps maintainers stay informed about which terms are not being tracked and why.
+
+When tracking is interrupted for a specific term, the system opens an issue that explains why the term is not being tracked and associates labels to categorize the cause of the tracking interruption. The system automatically closes issues when tracking resumes after declarations are fixed and deployed.
+
+## Understanding labels
+
+The reporting system uses labels to categorize issues and indicate what action is needed.
+
+### Auto-managed labels
+
+All labels that are marked with `- Auto-managed by OTA engine` visible in their description on hover are automatically managed by the engine.
+
+**These labels should not be manually added to issues, modified or removed from them, nor should their descriptions or colors be edited by maintainers.**
+
+The engine will automatically manage these labels as needed.
+
+### Issues requiring intervention
+
+The label `⚠ needs intervention` indicates that manual contributor intervention is required to restore tracking. When this label appears on an issue, it means the problem won't be resolved automatically and requires human action to fix the declarations or configuration.
+
+Issues without this label represent tracking interruptions that need investigation to determine the appropriate course of action. These issues may resolve themselves automatically once the underlying problem (such as a temporary network outage or service downtime) is fixed. However, some may not be fixable at all, for example when the tracking engine is detected and blocked as a bot by the target service.

content/collections/how-to/create-repositories.md

@@ -24,7 +24,7 @@ Before starting, ensure you have:
 ### Create from template
 
 1. Go to the [`demo-declarations`](https://github.com/OpenTermsArchive/demo-declarations) repository
-2. Click "Use this template" dropdown and select "Create a new repository"
+2. Click the "Use this template" drop-down menu and select "Create a new repository"
 3. Name it `<collection_id>-declarations` (e.g. `pga-declarations`)
 4. Wait 1-2 minutes for automatic setup to complete (check `first-time-setup` action status)
 

content/collections/how-to/terminate.md

@@ -5,7 +5,7 @@ weight: 4
 
 # How to terminate a collection
 
-If you don't have the resources to maintain a collection anymore, follow these steps to properly terminate it. This will make it clear to users and potential successors that it is no longer actively maintained and can be taken over.
+If you don't have the resources to maintain a collection any more, follow these steps to properly terminate it. This will make it clear to users and potential successors that it is no longer actively maintained and can be taken over.
 
 ## Steps