Rewrite contributing file

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/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
 

content/collections/reference/roles.md

@@ -119,7 +119,7 @@ Analyses terms changes to identify significant changes and produce reports in va
 
 #### Responsibilities
 
-- Identify and analyze meaningful terms changes
+- Identify and analyse meaningful terms changes
 - Produce insights from changes
 
 #### Tasks

content/collections/reference/status.md

@@ -31,6 +31,6 @@ Collection may be functional but shows clear signs of neglect.
 
 Collection has voluntarily ceased all operational activities.
 
-- No terms are tracked anymore, though historical records remain accessible for reference purposes.
+- No terms are tracked any more, though historical records remain accessible for reference purposes.
 - No technical maintenance is performed.
 - All [roles]({{< relref "collections/reference/roles" >}}) are inactive.

content/community/how-to/join.md

@@ -15,13 +15,13 @@ The Open Terms Archive community concentrates interactions on an instant chat pl
 
 **Use this [invitation link](https://community.opentermsarchive.org/signup_user_complete/?id=fb1tb45hnfnk3c88btjhsjoomc&md=link&sbr=fa) and create an account.**
 
-After successful login, you will be automatically be added to the **~Announcements** channel.
+After successful login, you will be automatically be added to the **~Announcements** channel.
 
 ## 2. Profile setup
 
-Once you're all set, the next thing is to set up your profile. A complete profile sets you up for meaningful interactions and connections with members interested in tracking the same terms.
+The next thing is to set up your profile. A complete profile sets you up for meaningful interactions and connections with members interested in tracking the same terms.
 
-This includes adding your full name, user name, pseudo (nickname), role, and profile picture.
+This includes adding your full name, user name, nickname, role, and profile picture.
 
 New members can set up their profiles by following these steps:
 
@@ -30,7 +30,7 @@ New members can set up their profiles by following these steps:
 
 ## 3. Introduce yourself
 
-After joining the Open Terms Archive chat, members are encouraged to briefly introduce themselves in the **~Introductions** channel.
+After joining the Open Terms Archive chat, members are encouraged to introduce themselves in the **~Introductions** channel.
 
 ## 4. Find your channels
 

content/deployment/how-to/deploy.md

@@ -156,7 +156,7 @@ This section uses [Ansible Vault](https://docs.ansible.com/ansible/latest/vault_
    ansible-vault encrypt .env
    ```
 
-   > **Note**: Running the command from the `deployment` folder will ensure that the `vault.key` file is used as vault key, since this folder contains an `ansible.cfg` file that explicitly configures this behavior.
+   > **Note**: Running the command from the `deployment` folder will ensure that the `vault.key` file is used as vault key, since this folder contains an `ansible.cfg` file that explicitly configures this behaviour.
    >
    > To decrypt an encrypted file, use:
    >

content/deployment/reference/architecture.md

@@ -67,7 +67,7 @@ The engine automatically creates issues in the declarations repository to notify
 
 ## Configuration files
 
-The system's behavior is controlled through several key configuration files:
+The system's behaviour is controlled through several key configuration files:
 
 - `inventory.yml`: Defines server address and deployment parameters
 - `production.json`: Stores application-specific settings

content/deployment/reference/server-specifications.md

@@ -15,9 +15,9 @@ Approximately 750 MB of storage is required for the engine itself, with the rem
 
 ## Storage
 
-Recommended storage: 10 GB, with resizable partitioning to enable growth over time.
+Recommended storage: 10 GB, with resizeable partitioning to enable growth over time.
 
-Storage usage typically grows at a rate of 0.5 MB per tracked terms per month on average for latin scripts. This growth rate varies depending on the type of service being tracked:
+Storage usage typically grows at a rate of 0.5 MB per tracked terms per month on average for Latin scripts. This growth rate varies depending on the type of service being tracked:
 
 - Services with large legal teams and heavy website layouts: ~1 MB per terms per month
 - Smaller services: ~0.1-0.3 MB per terms per month

content/federation/reference/criteria.md

@@ -15,7 +15,7 @@ A **collection** can **join** the Open Terms Archive **federation** if it abides
 6. Public and open-licensed **snapshots**, as evidenced by the `LICENSE` file in the snapshots repository.
 7. Public and open-licensed **versions**, as evidenced by the `LICENSE` file in the versions repository.
 8. Regular, public, and open-licensed **dataset** releases, as evidenced by the `LICENSE` file in the datasets.
-9. Publicly accessible API with median response time under 20ms, as evidenced by uptime tracking logs.
+9. Publicly accessible API with median response time under 20 ms, 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" >}}).

content/terms/guideline/choosing-selectors.md

@@ -15,7 +15,7 @@ Selectors are used in the [`select`]({{< relref "terms/reference#select" >}}) an
 
 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).
+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).
 
 ## Choosing durable selectors eases maintenance