Refactor documentation

.markdownlint.yml

@@ -14,6 +14,7 @@ no-inline-html:
   allowed_elements:
     - abbr
     - i
+    - filename
 
 no-duplicate-header: false
 

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,39 @@
+---
+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 exposes the data it collects through datasets and through its own API. The Federation API unifies search and discovery across collections.
+
+## Required minimal terminology
+
+Before diving into the details, let's first understand the essential terminology used throughout this documentation.
+
+- **Terms:** the contractual documents published by services (such as Terms of Service, Privacy Policy, Community Guidelines…) that users agree to.
+- **Collection:** a set of tracked terms grouped by a specific scope (such as language, jurisdiction, industry…).
+- **Declaration:** a JSON file that defines which terms to track for a service and how to track them.
+- **Snapshot:** the original source document (HTML, PDF…) from which the terms will be extracted.
+- **Version:** the textual content of the terms after filtering out irrelevant content (navigation menu, advertisements…) from a snapshot.
+
+## Documentation structure
+
+This documentation follows the [Diátaxis](https://diataxis.fr) approach and structures content in different categories:
+
+- **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 configuration options and specifications for advanced users.
+- **Explanations:** background knowledge that enables understanding the constraints and how choices that are made.
+
+### Table of contents
+
+- **Analysis:** guidance on how to analyze terms changes, from navigating through the history of tracked documents 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.
+- **Federation:** constraints and benefits of joining the Open Terms Archive federation.
+- **Deployment:** guidance on operating an Open Terms Archive instance.
+- **Programmatic access:** documentation on the engine CLI and APIs.
+- **Concepts and principles:** main concepts, terminology and fundamental design principles of Open Terms Archive.

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,7 +1,9 @@
 ---
-title: "How to navigate history"
+title: Navigate history
 weight: 1
-aliases: /navigate-history/
+aliases:
+  - /navigate-history/
+  - /terms/how-to-navigate-history/
 ---
 
 # How to navigate history

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

@@ -1,5 +1,6 @@
 ---
-title: "How to publish a memo"
+title: Publish a memo
+aliases: /memos/how-to-publish/
 ---
 
 # How to publish a memo
@@ -10,7 +11,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,6 @@
 ---
-title: "Copywriting reference"
+title: Copywriting
+aliases: /memos/copywriting-reference/
 ---
 
 # 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,63 @@
+---
+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 terms
+
+{{< configOption name="ota track" 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" description="Show help and available options for track command" example="`npx ota track --help`" >}}
+
+{{< configOption name="ota track [--services <service_id>...]" description="Track terms of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\"`" >}}
+
+{{< configOption name="ota track [--services <service_id>...] [--types <terms_type>...]" description="Track specific terms types of specific services only" example="`npx ota track --services \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" >}}
+
+{{< configOption name="ota track --schedule [--services <service_id>...] [--types <terms_type>...]" description="Track terms on the schedule defined in the configuration" example="`npx ota track --schedule`" >}}
+
+## Validating declarations
+
+{{< configOption name="ota validate [--services <service_id>...] [--types <terms_type>...]" 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 \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" >}}
+
+{{< configOption name="ota validate --schema-only [--services <service_id>...] [--types <terms_type>...]" 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 \"Facebook\" \"LinkedIn\" --types \"Privacy Policy\" \"Terms of Service\"`" >}}
+
+{{< configOption name="ota validate --modified" description="Run ota validate only on files that have been modified in Git" example="`npx ota validate --modified`" >}}
+
+## Linting declarations
+
+{{< configOption name="ota lint [--services <service_id>...]" description="Test the format of declarations' normalisation." example="`npx ota lint --services \"Facebook\" \"LinkedIn\"`" >}}
+
+{{< configOption name="ota lint --fix [--services <service_id>...]" description="Automatically correct formatting mistakes and ensure that all declarations are standardised" example="`npx ota lint --fix`" >}}
+
+{{< configOption name="ota lint --modified" description="Run ota lint only on files that have been modified in Git" example="`npx ota lint --modified`" >}}
+
+## Publishing dataset
+
+{{< configOption name="ota dataset [--file <filename>]" 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 dataset.zip`" >}}
+
+To export the dataset into a ZIP file and publish it on GitHub releases:
+
+{{< configOption name="ota dataset --publish [--file <filename>]" 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]({{< relref "collections/reference/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 [--file <filename>]" 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 [--file <filename>]" 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" description="Start the collection Web API server. The Web API will be available under `<http://localhost>:<port>/<basePath>/<apiVersion>/<resource>`. The server port and base path are defined in the configuration." example="`npx ota serve`" >}}

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,15 +1,15 @@
 ---
-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.
+As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code.
 
 ## `fetch`
 
-The `fetch` module gets the MIME type and content of a document from its URL
+`fetch` gets the MIME type and content of a document from its URL
 
 ```js
 import fetch from '@opentermsarchive/engine/fetch';
@@ -31,11 +31,11 @@ await fetch({ executeClientScripts: true, ... });
 await stopHeadlessBrowser();
 ```
 
-The `fetch` module options are defined as a [`node-config` submodule](https://github.com/node-config/node-config/wiki/Sub-Module-Configuration). The default `fetcher` configuration can be overridden by adding a `fetcher` object to the local configuration file.
+The `fetch` options are defined as a [`node-config` submodule](https://github.com/node-config/node-config/wiki/Sub-Module-Configuration). The default `fetcher` configuration can be overridden by adding a `fetcher` object to the local configuration file.
 
 ## `extract`
 
-The `extract` module transforms HTML or PDF content into a Markdown string according to a declaration.
+`extract` transforms HTML or PDF content into a Markdown string according to a declaration.
 
 ```js
 import extract from '@opentermsarchive/engine/extract';

content/collections/_index.md

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