Refactor documentation

config/_default/module.yaml

@@ -0,0 +1,5 @@
+mounts:
+  - source: assets
+    target: assets
+  - source: node_modules/minireset.css/minireset.css
+    target: assets/css/vendor/minireset.css

content/_index.md

@@ -0,0 +1,28 @@
+---
+title: Open Terms Archive documentation
+linkTitle: Homepage
+weight: 1
+---
+
+# Open Terms Archive documentation
+
+Open Terms Archive is a decentralised system that tracks collections of services' terms across multiple servers. Each collection operates its own API, and the Federation API unifies search and discovery across collections, fostering collaboration with external applications.
+
+### Documentation structure
+
+In this documentation you can find the following kind of content to support users at different levels:
+
+- **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.
+- **Reference:** Comprehensive technical documentation detailing system components, configuration options, and specifications for advanced users.
+
+### Main contents
+
+- **[Analysis](/analysis/):** Provides guidance on how to analyze terms changes, from navigating through the history of tracked documents to publishing memos about significant changes, along with copywriting guidelines for creating analysis content.
+- **[Community](/community/):** Provides information on how to join and participate in the Open Terms Archive community.
+- **[Terms](/terms/):** Provides guidance on tracking and maintaining terms declarations, reference documentation for declaration formats, and guidelines for selecting selectors and reviewing contributions.
+- **[Collections](/collections/):** Provides guidance on creating and managing collections of tracked terms, creating repositories and defining metadata, and detailed reference documentation for configuration options, environment variables, governance roles, and collection metadata formats.
+- **[Federation](/federation/):** Explains the benefits of joining the Open Terms Archive federation, and the criteria that collections must meet to be part of the federated ecosystem.
+- **[Deployment](/deployment/):** Guides to deploy a collection.
+- **[Programmatic access](/api/):** Provides documentation for programmatically interacting with Open Terms Archive.
+- **[Concepts and principles](/concepts/):** Explains the main concepts and terminology of Open Terms Archive and fundamental design principles.

content/analysis/_index.md

@@ -0,0 +1,5 @@
+---
+title: "Analysis"
+weight: 2
+---
+

content/analysis/how-to/_index.md

@@ -0,0 +1,4 @@
+---
+title: How to
+weight: 1
+---

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

@@ -1,5 +1,5 @@
 ---
-title: "How to navigate history"
+title: Navigate history
 weight: 1
 aliases: /navigate-history/
 ---

content/memos/how-to-publish.en.md → content/analysis/how-to/publish-memo.md

@@ -1,5 +1,5 @@
 ---
-title: "How to publish a memo"
+title: Publish a memo
 ---
 
 # How to publish a memo
@@ -10,7 +10,7 @@ No technical skills are required.
 
 ## Prerequisites
 
-- A drafted memo compliant with the [copywriting reference]({{< relref "/memos/copywriting-reference" >}}).
+- A drafted memo compliant with the [copywriting reference]({{< relref "/analysis/reference/copywriting" >}}).
 
 ## 1. Send
 

content/analysis/reference/_index.md

@@ -0,0 +1,4 @@
+---
+title: Reference
+weight: 2
+---

content/memos/copywriting-reference.en.md → content/analysis/reference/copywriting.md

@@ -1,5 +1,5 @@
 ---
-title: "Copywriting reference"
+title: Copywriting
 ---
 
 # Copywriting reference

content/api/_index.md

@@ -1,4 +1,4 @@
 ---
-title: API
-weight: 4
+title: Programmatic access
+weight: 8
 ---

content/api/cli.md

@@ -0,0 +1,61 @@
+---
+title: Command line interface
+weight: 1
+---
+
+# Command line interface
+
+Once the engine module is installed as a dependency within another module, the `ota` command with the following subcommands is available.
+
+In these commands:
+
+- **`<service_id>`** is the case sensitive name of the service declaration file without the extension. For example, for `Twitter.json`, the service ID is `Twitter`.
+- **`<terms_type>`** is the property name used under the `documents` property in the declaration to declare a terms. For example, in the getting started declaration, the terms type declared is `Privacy Policy`.
+
+#### Tracking
+
+{{< configOption name="ota track" type="command" description="Track the current terms of services according to provided declarations. The declarations, snapshots and versions paths are defined in the configuration." example="npx ota track" >}}
+
+> Note that the snapshots and versions will be recorded at the moment the command is executed, on top of the existing local history. If a shared history already exists and the goal is to add on top of it, that history has to be downloaded before executing that command.
+
+{{< configOption name="ota track --help" type="command" description="Show help and available options for track command" example="npx ota track --help" >}}
+
+{{< configOption name="ota track --services" type="command" description="Track terms of specific services only" example="npx ota track --services \"<service_id>\" [\"<service_id>\"...]" >}}
+
+{{< configOption name="ota track --services --types" type="command" description="Track specific terms types of specific services only" example="npx ota track --services \"<service_id>\" [\"<service_id>\"...] --types \"<terms_type>\" [\"<terms_type>\"...]" >}}
+
+{{< configOption name="ota track --schedule" type="command" description="Track terms on a schedule (four times daily)" example="npx ota track --schedule" >}}
+
+#### Validating
+
+{{< configOption name="ota validate" type="command" 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 <service_id>...] [--types <terms_type>...]" >}}
+
+{{< configOption name="ota validate --schema-only" type="command" 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 <service_id>...] [--types <terms_type>...]" >}}
+
+{{< configOption name="ota validate --modified" type="command" description="Run ota validate only on files that have been modified in Git" example="npx ota validate --modified" >}}
+
+#### Linting
+
+{{< configOption name="ota lint" type="command" description="Test the format of declarations' normalisation. Use --fix to automatically correct formatting mistakes and ensure that all declarations are standardised." example="npx ota lint [--services <service_id>...] [--fix] [--modified]" >}}
+
+#### Dataset publishing
+
+{{< configOption name="ota dataset" type="command" 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 <filename>]" >}}
+
+To export the dataset into a ZIP file and publish it on GitHub releases:
+
+{{< configOption name="ota dataset --publish" type="command" 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](#environment-variables).
+
+To export, publish the dataset and remove the local copy that was created after it has been uploaded:
+
+{{< configOption name="ota dataset --publish --remove-local-copy" type="command" description="Export, publish dataset and remove local copy after upload" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --publish --remove-local-copy" >}}
+
+{{< configOption name="ota dataset --schedule" type="command" description="Schedule export, publishing and local copy removal" example="GITHUB_TOKEN=ghp_XXXXXXXXX npx ota dataset --schedule --publish --remove-local-copy" >}}
+
+#### Exposing the collection API
+
+{{< configOption name="ota serve" type="command" description="Start the collection Web API server. The Web API will be available under http://localhost:<port>/<basePath>/<apiVersion>/<resource>. The server port and basePath are defined in the configuration." example="npx ota serve" >}}
+
+> For example, with the default configuration, the list of services can be found at [`http://localhost:3000/api/v1/services`](http://localhost:3000/api/v1/services).

content/api/collection.en.md → content/api/collection.md

@@ -1,9 +1,9 @@
 ---
-title: Collection
+title: Collection REST API
 weight: 2
 ---
 
-# Collection Web API [Beta]
+# Collection REST API
 
 As Open Terms Archive is decentralised, each instance embarks its own API. The documentation relevant to the specific version of the engine on that instance is provided on that instance itself.
 

content/api/federation.en.md → content/api/federation.md

@@ -1,10 +1,10 @@
 ---
-title: Federation
+title: Federation REST API
 weight: 3
 aliases: /api/federated/
 ---
 
-# Federation API
+# Federation REST API
 
 Open Terms Archive is a decentralised system that tracks collections of services' terms across multiple servers. Each collection operates its own API, and the Federation API unifies search and discovery across collections, fostering collaboration with external applications.
 

content/api/node.en.md → content/api/node.md

@@ -1,9 +1,9 @@
 ---
-title: Node
+title: Node.js module
 weight: 1
 ---
 
-# Node.js API [Beta]
+# Node.js module
 
 As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code. The following modules are available.
 

content/collections/_index.md

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