Document federation

content/_index.en.md

@@ -21,30 +21,23 @@ _Words in bold are [business domain names](https://en.wikipedia.org/wiki/Domain-
 
 ## Main concepts
 
-### Instances
+### Collection
 
-Open Terms Archive is a decentralised system.
-
-It aims at enabling any entity to **track** **terms** on its own and at federating a number of public **instances** in a single ecosystem to maximise discoverability, collaboration and political power. To that end, the Open Terms Archive **engine** can be run on any server, thus making it a dedicated **instance**.
-
-> Federated public instances can be [found on GitHub](
-https://github.com/OpenTermsArchive?q=declarations).
-
-### Collections
-
-An **instance** **tracks** **terms** of a single **collection**.
+Open Terms Archive is a decentralised system. It aims at enabling any entity to **track** **terms** on its own. To that end, the Open Terms Archive **engine** can be run on any server, thus making it a dedicated **instance**. An **instance** **tracks** **terms** within a single **collection**.
 
 A **collection** is characterised by a **scope** across **dimensions** that describe the **terms** it **tracks**, such as **language**, **jurisdiction** and **industry**.
 
-> Federated public collections can be [found on GitHub](https://github.com/OpenTermsArchive?q=versions).
-
 #### Example scope
 
 > The terms tracked in this collection are:
 > - Of dating services used in Europe.
 > - In the European Union and Switzerland jurisdictions.
 > - In English, unless no English version exists, in which case the primary official language of the jurisdiction of incorporation of the service operator will be used.
 
+### Federation
+
+In order to maximise discoverability, collaboration and political power, public **collections** are **federated** within a single ecosystem. This makes their data mutually discoverable and enables mutualising effort.
+
 ### Terms types
 
 To distinguish between the different **terms** of a **service**, each has a **type**, such as “Terms of Service”, “Privacy Policy”, “Developer Agreement”…
@@ -105,9 +98,8 @@ Such a dataset can be generated from **versions** alone. If **snapshots** and **
 
 This documentation describes how to execute the **engine** independently from any specific **instance**. For other use cases, other parts of the documentation could be more relevant:
 
-- to contribute **declarations** to an existing **instance**, see [how to contribute terms]({{< relref "contributing-terms" >}});
-- to create a new **collection**, see [collection creation]({{< relref "create-new-collection" >}}) documentation;
-- to create a new public **instance**, see the [governance]({{< relref "governance" >}}) documentation.
+- to contribute **declarations** to an existing **collection**, see [contributing terms]({{< relref "contributing-terms" >}});
+- to create a new **collection**, see [creating a new collection]({{< relref "collections/create" >}}).
 
 ### Requirements
 

content/collections/_index.md

@@ -0,0 +1,4 @@
+---
+title: Collections
+weight: 3
+---

content/create-new-collection.en.md → content/collections/create.en.md

@@ -1,25 +1,19 @@
 ---
-title: "Creating a collection"
-weight: 2
+title: Creating a collection
 ---
 
 # Creating a collection
 
 ## Define the necessary metadata
 
-First of all, define the scope and metadata of the collection:
-- Concise description of the collection topic (examples: `Largest global social media`, `Most used social media in France`, `Dating apps`, `Platforms providing services to businesses`…)
-- Collection name (3 words maximum, examples: `Platform Governance Archive`, `France Élections`, `Dating`, `P2B Compliance Assessment`…)
-- Collection ID (examples: `pga`, `France-elections`, `dating`, `p2b-compliance`…)
-- Terms language (examples: `English`, `French`, `All EU languages`…)
-- Terms jurisdiction (examples: `EU`, `France`, `EEA`, `USA`, `global`…)
-- Collection maintainer entity (name, logo, url)
+First of all, define the [metadata]({{< relref "collections/metadata" >}}) and [governance]({{< relref "collections/governance" >}}) of the collection.
 
 ## Create repositories
 
 ### Declarations
 
 Create the collection declarations repository by using the [`demo-declarations`](https://github.com/OpenTermsArchive/demo-declarations) repository as template:
+
 - Go to the [`demo-declarations` repository](https://github.com/OpenTermsArchive/demo-declarations)
 - Click on the “Use this template” dropdown and select “Create a new repository”
 - Set the repository name to `<collection_id>-declarations`. For example: `pga-declarations`.
@@ -29,7 +23,7 @@ Create the collection declarations repository by using the [`demo-declarations`]
 
 - Click on the little cogwheel icon next to the “About” block.
 - Set the description to “Declarations for `<collection_name>`. Maintained by `<maintainer>`.”
-- Set website: https://opentermsarchive.org
+- Set website to `https://opentermsarchive.org`, or any other relevant dedicated website.
 - Add the following tags: `terms-of-service`, `terms-of-service-agreements`, `terms-and-conditions`, `open-terms-archive`.
 - Uncheck “Releases”, “Packages” and “Deployments”.
 
@@ -38,20 +32,24 @@ Create the collection declarations repository by using the [`demo-declarations`]
 These settings ease the whole contribution process.
 
 In “General → Features”:
+
 - Disable “Wikis”.
 - Disable “Projects”.
 
 In “General → Pull Requests”:
+
 - Check only the “Allow squash merging” option, and set it to “Default to pull request title and commit details”.
 - Enable “Allow auto-merge”.
 - Enable “Automatically delete head branches”.
 
 In “Branches”:
+
 - Add a branch protection rule for `main`.
   - Check “Require a pull request before merging”, check "Require approvals" and set “Required number of approvals before merging” to 1.
   - Check “Require status checks to pass before merging” and add `validate_modified_declarations` and `validate_schema` as required status checks.
 
 In “Actions → General → Actions permissions”:
+
 - Select “Allow all actions and reusable workflows”.
 
 #### Remove default labels
@@ -67,6 +65,7 @@ Issues labels will be added by the engine as problems are encountered when track
 ### Snapshots
 
 Create the snapshots repository by using the [`demo-snapshots` repository](https://github.com/OpenTermsArchive/demo-snapshots) as template:
+
 - Go to the [`demo-snapshots` repository](https://github.com/OpenTermsArchive/demo-snapshots)
 - Click on the “Use this template” dropdown and select “Create a new repository”
 - Set the repository name to `<collection_id>-snapshots`.
@@ -75,7 +74,7 @@ Create the snapshots repository by using the [`demo-snapshots` repository](https
 #### Fill the “About” section
 
 - Set the description: “Documents snapshots for `<collection_name>`. Maintained by `<maintainer>`.”
-- Set website: https://opentermsarchive.org
+- Set website to `https://opentermsarchive.org`.
 - Add the following tags: `terms-of-service`, `terms-of-service-agreements`, `terms-and-conditions`, `open-terms-archive`.
 - Uncheck “Releases”, “Packages” and “Deployments”.
 
@@ -84,14 +83,17 @@ Create the snapshots repository by using the [`demo-snapshots` repository](https
 These settings aim at minimising the otherwise overwhelming amount of information and click targets.
 
 In “General → Features”:
+
 - Uncheck “Wikis”, “Issues”, “Discussions” and “Projects”.
 
 In “Actions → General → Actions permissions”:
+
 - Select “Disable actions”.
 
 ### Versions
 
 Create the versions repository by using the [`demo-versions` repository](https://github.com/OpenTermsArchive/demo-versions) as template:
+
 - Go to the [`demo-versions` repository](https://github.com/OpenTermsArchive/demo-versions)
 - Click on the “Use this template” dropdown and select “Create a new repository”
 - Set the repository name to `<collection_id>-versions`.
@@ -100,7 +102,7 @@ Create the versions repository by using the [`demo-versions` repository](https:/
 #### Fill the “About” section
 
 - Set the description: “Terms versions for `<collection_name>`. Maintained by `<maintainer>`.”
-- Set website: https://docs.opentermsarchive.org/navigate-history/
+- Set website to `https://docs.opentermsarchive.org/navigate-history/`
 - Add the following tags: `terms-of-service`, `terms-of-service-agreements`, `terms-and-conditions`, `open-terms-archive`.
 - Uncheck “Packages” and “Deployments”.
 
@@ -109,18 +111,18 @@ Create the versions repository by using the [`demo-versions` repository](https:/
 These settings aim at minimising the otherwise overwhelming amount of information and click targets.
 
 In “General → Features”:
+
 - Uncheck “Wikis”, “Issues”, “Discussions” and “Projects”.
 
 In “Actions → General → Actions permissions”:
+
 - Select “Disable actions”.
 
 #### Update README
 
 - Update the README file with proper metadata.
 
-- - -
-
-## Set up GitHub maintenance teams
+## Set up GitHub teams
 
 For collections to be included in the Open Terms Archive organisation only. For third parties, handle rights however you see fit.
 
@@ -134,18 +136,16 @@ For collections to be included in the Open Terms Archive organisation only. For
 - Add the versions repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)
 - Add the declarations, snapshots and versions repositories to the Bots team with “Write” access
 
-- - -
-
-## Setup deployment
+## Set up deployment
 
 ### On the server
 
-- Connect to the server with `ssh <username>@<host>` (example usernames: `debian`, `ubuntu`…)
+- Connect to the server with `ssh <username>@<host>` (usual usernames: `debian`, `ubuntu`…)
 - Create a new SSH key: `ssh-keygen -q -N "" -f ~/.ssh/ota-deploy`
 - Add the public key to `authorized_keys`: `cat ~/.ssh/ota-deploy.pub >> ~/.ssh/authorized_keys`
-	- Copy the public key with `cat ~/.ssh/ota-deploy.pub` and keep it temporarily for the next steps
+  - Copy the public key with `cat ~/.ssh/ota-deploy.pub` and keep it temporarily for the next steps
 - Add the private key to the SSH authentication agent: `ssh-add ~/.ssh/ota-deploy` (start the SSH agent before if necessary with `eval ${ssh-agent -s}`)
-	- Copy the private key with `cat ~/.ssh/ota-deploy` and keep it temporarily for the next steps
+  - Copy the private key with `cat ~/.ssh/ota-deploy` and keep it temporarily for the next steps
 
 Note: user must have the right to `sudo`.
 
@@ -164,8 +164,6 @@ Fill `deployment/inventory.yml`:
 - `ansible_user: <username>` (example: `debian`)
 - `ed25519_fingerprint: <server_ssh_fingerprint>`
 
-- - -
-
 ## Test
 
 ### Via GitHub Actions

content/collections/governance.en.md

@@ -0,0 +1,17 @@
+---
+title: Governance
+---
+
+# Collection governance
+
+Setting up and maintaining a collection is done by fulfilling certain tasks. These tasks are handled through roles.
+
+1. A **curator**, who decides what services and terms are welcome in the collection.
+2. A **host**, who ensures that a server is available.
+3. An **administrator**, who takes responsibility for ensuring that the engine and associated software tools are functional and up to date.
+4. **Maintainers**, who guarantee the quality of the tracked versions by reviewing contributions.
+5. **Contributors**, who add declarations and keep them up to date.
+
+Each of these roles can be volunteer or paid, and all can be handled by one single or many different entities.
+
+The Open Terms Archive core team provides processes and tools to support all of these roles.

content/collections/metadata.en.md

@@ -0,0 +1,14 @@
+---
+title: Metadata
+---
+
+# Collection metadata
+
+A collection is defined by the following metadata:
+
+- Concise description of the collection topic (examples: `Largest global social media`, `Most used social media in France`, `Dating apps`, `Platforms providing services to businesses`…).
+- Collection name (3 words maximum, examples: `Platform Governance Archive`, `France Élections`, `Dating`, `P2B Compliance Assessment`…).
+- Collection ID (examples: `pga`, `France-elections`, `dating`, `p2b-compliance`…).
+- Terms language (examples: `English`, `French`, `All EU languages`…).
+- Terms jurisdiction (examples: `EU`, `France`, `EEA`, `USA`, `global`…).
+- Entities (name, logo, url) for each of the [roles]({{< relref "collections/governance" >}}).

content/federation.en.md

@@ -0,0 +1,35 @@
+---
+title: Federation
+weight: 6
+---
+
+# Federation
+
+Open Terms Archive is a decentralised system. It aims at enabling any entity set up their own collections and track terms on their own.
+
+In order to maximise discoverability, collaboration and political power, public collections are federated within a single ecosystem. This makes their data mutually discoverable and enables mutualising effort.
+
+## Benefits
+
+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 [Federated API]({{< relref "api" >}}).
+5. Public announcement through all Open Terms Archive communication channels upon joining.
+
+## 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/metadata" >}}).
+2. Clearly defined [collection governance]({{< relref "collections/governance" >}}).
+3. The vast majority of **versions** are readable.
+4. **Frequency** of at least one track a day.
+5. Public and open-licensed **snapshots**.
+6. Public and open-licensed **versions**.
+7. Regular, public, and open-licensed **dataset** releases.
+8. Publicly accessible API with median response time under 20ms.
+
+_Please note that the federation is an ongoing effort. While criteria are assessed and refined to strike the right balance between accessibility and quality, the Open Terms Archive core team is responsible for assessing which collections may join the federation, and has the right to update the criteria as requests for joining are made._