Improve Collections documentation

#111

Author: MattiSG

content/api/_index.md

@@ -1,4 +1,4 @@
 ---
 title: API
-weight: 7
+weight: 6
 ---

content/collections/create.en.md

@@ -1,18 +1,29 @@
 ---
 title: Creating a collection
+weight: 3
 ---
 
 # Creating a collection
 
-## Define the necessary metadata
+## Define metadata
 
-First of all, define the [metadata]({{< relref "collections/metadata" >}}) and [governance]({{< relref "collections/governance" >}}) of the collection.
+First of all, define the [metadata]({{< relref "collections/metadata" >}}) of the collection you would like to create.
+
+## 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/governance" >}}) of your collection.
+
+At any time, feel free to ask for help or partners in the community.
 
 ## Create repositories
 
+Collections rely on three git repositories being set up to hold the data.
+
+The instructions below assume the usage of GitHub to host repositories. If you don't use GitHub, try to set up the equivalent metadata in your git hosting platform. Contributions to the documentation to make it independent from GitHub are very welcome!
+
 ### Declarations
 
-Create the collection declarations repository by using the [`demo-declarations`](https://github.com/OpenTermsArchive/demo-declarations) repository as template:
+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”
@@ -31,26 +42,19 @@ 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”.
+- 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
 
@@ -82,13 +86,13 @@ 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”.
+- In “General → Features”
+  - Uncheck “Wikis”.
+  - Uncheck “Issues”.
+  - Uncheck “Discussions”.
+  - Uncheck “Projects”.
+- In “Actions → General → Actions permissions”
+  - Select “Disable actions”.
 
 ### Versions
 
@@ -104,19 +108,20 @@ Create the versions repository by using the [`demo-versions` repository](https:/
 - Set the description: “Terms versions for `<collection_name>`. Maintained by `<maintainer>`.”
 - 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”.
+- Uncheck “Packages”.
+- Uncheck “Deployments”.
 
 #### Define repository settings
 
 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”.
+- In “General → Features”
+  - Uncheck “Wikis”.
+  - Uncheck “Issues”.
+  - Uncheck “Discussions”.
+  - Uncheck “Projects”.
+- In “Actions → General → Actions permissions”
+  - Select “Disable actions”.
 
 #### Update README
 
@@ -129,7 +134,7 @@ For collections to be included in the Open Terms Archive organisation only. For
 - [Create a new collection team](https://github.com/orgs/OpenTermsArchive/new-team)
 - Give it the name of the collection
 - Set as avatar the collection icon from the website
-- Set as description: “Maintainers of the <collection_name> collection”
+- Set as description: “Maintainers of the `<collection_name>` collection”
 - Add selected members to the team
 - Add the declarations repository to the collection team, with “Maintain” access rights
 - Add the snapshots repository to the collection team, with “Triage” access rights (giving them more would enable them to corrupt data)

content/federation.en.md renamed to content/collections/federation.en.md

@@ -1,6 +1,6 @@
 ---
 title: Federation
-weight: 6
+weight: 4
 ---
 
 # Federation
@@ -34,4 +34,6 @@ A **collection** can **join** the Open Terms Archive **federation** if it abides
 9. Publicly accessible API with median response time under 20ms.
 10. Abide by all software and data licenses.
 
-_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._
+## Disclaimer
+
+Please note that establishing 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.

content/collections/governance.en.md

@@ -1,17 +1,28 @@
 ---
 title: Governance
+weight: 2
 ---
 
 # Collection governance
 
-Setting up and maintaining a collection is done by fulfilling certain tasks. These tasks are handled through roles.
+Setting up and maintaining a collection needs fulfilling certain tasks. These tasks are handled through roles. Each of these roles can be volunteer or paid, and can be handled by one single or several different entities. The Open Terms Archive core team provides processes and tools to support all of these 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.
+## Host
 
-Each of these roles can be volunteer or paid, and all can be handled by one single or many different entities.
+This role ensures that a server and internet access is available to run the engine on and fetch the terms, either by using its own infrastructure or renting a server on a hosting provider.
 
-The Open Terms Archive core team provides processes and tools to support all of these roles.
+## Administrator
+
+This role takes responsibility for ensuring that the engine and associated software tools are functional and up to date.
+
+## Curator
+
+This role decides which services and terms are welcome in the collection.
+
+## Maintainer
+
+This role guarantees the quality of the tracked versions by reviewing contributions.
+
+## Contributor
+
+This role adds declarations and keeps them up to date.

content/collections/metadata.en.md

@@ -1,14 +1,67 @@
 ---
 title: Metadata
+weight: 1
 ---
 
 # Collection metadata
 
-A collection is defined by the following 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" >}}).
+## Description
+
+A concise description of the collection topic.
+
+### Examples
+
+- Largest global social media
+- Most used social media in France
+- Dating apps
+- Platforms providing services to businesses
+
+## Name
+
+Three words maximum.
+
+### Examples
+
+- Platform Governance Archive
+- France Élections
+- Dating
+- P2B Compliance Assessment
+
+## ID
+
+An identifier derived from the collection name that can more easily be referenced in code. Use acronyms and replace spaces with dashes.
+
+### Examples
+
+- `pga`
+- `France-elections`
+- `dating`
+- `p2b-compliance`
+
+## Language
+
+The expected language of the terms in the collection.
+
+### Examples
+
+- `English`
+- `French`
+- `All EU languages`
+
+## Jurisdiction
+
+The expected jurisdiction in which the terms in the collection apply.
+
+### Examples
+
+- `EU`
+- `France`
+- `EEA`
+- `USA`
+- `global`
+
+## Roles
+
+The name, URL and logo of the entities that will take responsibility for each of the necessary governance [roles]({{< relref "collections/governance" >}}).