Add Diataxis structure to our documentation (#1632)

The current documentation site contains a mix of documents without a
clear structure, making it difficult to navigate and onboard new users.

This PR takes the first step toward improving organization by adopting
the [Diátaxis framework](https://diataxis.fr/). Existing documents have
been reorganized into four categories: Tutorials, How-To Guides,
Reference, and Explanation.

The new structure is based on the [following
roadmap](https://hackmd.io/UVd1tfaVQtOrHcK2xnPZaQ), co-authored with
@jasagredo.

[This
issue](#1631)
encompasses the entire documentation reorganization process. The goal is
to consistently add content to the documentation site by allocating a
fixed number of hours per week (eg 4) to this task.

Author: dnadales

CONTRIBUTING.md

@@ -90,7 +90,7 @@ EOF
 
 An alternative to using `nix` is to set up the development
 environment yourself. Follow [these
-instructions](https://developers.cardano.org/docs/get-started/cardano-node/installing-cardano-node/)
+instructions](https://developers.cardano.org/docs/operate-a-stake-pool/node-operations/installing-cardano-node/#building-via-cabal)
 to properly configure your system.
 
 # Building the project
@@ -181,12 +181,11 @@ This section contain guidelines on what to check when making a pull request.
 - When bumping version bounds on the dependencies *it is not necessary* to
   increase the package version number. See [this
   section](#updating-the-dependencies-bounds).
-- When you want to create a changelog entry, follow [this and the following
-  section](docs/website/contents/for-developers/ReleaseProcess.md#installing-scriv).
+- When you want to create a changelog entry, follow [this and the following section](docs/website/contents/howtos/contributing/how_to_make_a_release.md#installing-scriv).
 
 ## Following our git process
 
-Our [git process](docs/website/contents/for-developers/GitProcess.md) describes
+Our [git process](docs/website/contents/howtos/contributing/consensus_git_process.md) describes
 the `git` practices we encourage when working with the code in this repository.
 
 ## Updating the documentation
@@ -197,7 +196,7 @@ documentation (see [this section](#documentation)).
 ## Following the style guide
 
 We have a [Haskell style
-guide](docs/website/contents/for-developers/StyleGuide.md) that should be
+guide](docs/website/contents/howtos/contributing/style_guide.md) that should be
 followed when writing code in Consensus. Our style guide is not set in stone,
 and improvements are always welcome.
 
@@ -252,12 +251,12 @@ frustrations later on in the process.
 
 We maintain a changelog. If your pull request requires a changelog entry, please
 follow [these
-instructions](docs/website/contents/for-developers/ReleaseProcess.md#adding-a-changelog-fragment).
+instructions](docs/website/contents/howtos/contributing/how_to_make_a_release.md#adding-a-changelog-fragment).
 Even if your change doesn't require a changelog fragment, create an empty one as
 CI will reject your change otherwise. We made this choice to ensure authors of
 PRs would always take a moment to consider whether a changelog fragment should
 be added for their PR. For more information see [our release
-process](docs/website/contents/for-developers/ReleaseProcess.md).
+process](docs/website/contents/howtos/contributing/how_to_make_a_release.md).
 
 When creating a pull-request (PR), it is **crucial** that the PR:
 

docs/website/README.md

@@ -1,64 +1,72 @@
-The website for `ouroboros-consensus` is generated using [docusaurus](https://docusaurus.io/). If you want to build and view the generated website see Section [_Building the website_](#building-the-website).
+The website for `ouroboros-consensus` is generated using [Docusaurus](https://docusaurus.io/). To build and view the generated website, see [_Building the website_](#building-the-website).
 
-# Website content
+# Website Content
 
-The website source pages can be found in the [`contents`](./contents) directory. We divide our pages into two main categories:
+The front page is defined in the [`index.js`](src/components/HomepageFeatures/index.js) file. The main sections are configured in [`docusaurus.config.js`](./docusaurus.config.js).
 
-- "About Ouroboros", which contains high-level information about the Consensus protocols that the code in this repository implements. The pages for this category should be placed in the [`contents/about-ouroboros`](./contents/about-ouroboros) directory.
-- "For Developers", which contains information relevant for contributors to the Consensus code base. The pages for this category should be placed in the [`contents/for-developers`](./contents/for-developers) directory.
+The website's source pages are located in the [`contents`](./contents) directory. In accordance with the [Diátaxis framework](https://diataxis.fr/) for organizing technical documentation, we categorize our pages into four sections:
 
-The pages are written in Markdown format.
+- **Explanations** ([`contents/explanations`](./contents/explanations))
+- **Tutorials** ([`contents/tutorials`](./contents/tutorials))
+- **HOWTOs** ([`contents/howtos`](./contents/howtos))
+- **Reference** ([`contents/reference`](./contents/references))
 
-## Adding a new page
+Refer to the [Diátaxis framework](https://diataxis.fr/) for guidance on the type of documentation that belongs in each section.
 
-To add a new page create a Markdown file inside the appropriate directory (either [`contents/about-ouroboros`](./contents/about-ouroboros) or [`contents/for-developers`](./contents/for-developers) depending on the category). Then edit the [`sidebars.js`](./sidebars.js) file and add a reference to the new page in the desired place inside the sidebar item's configuration. For instance, if you add a new page `for-developers/foo.md`, Docusaurus will generate a reference called `for-developers/foo`, which can be used to add an entry to the sidebar as follows:
+All pages are written in Markdown format.
+
+## Adding a New Page
+
+To add a new page, create a Markdown file inside the appropriate directory (e.g., [`contents/explanations`](./contents/explanations)), based on the Diátaxis category the page belongs to.
+
+Next, update [`sidebars.js`](./sidebars.js) and add a reference to the new page in the sidebar configuration. For example, if you add `reference/foo.md`, Docusaurus will generate a reference called `reference/foo`, which can be added to the sidebar as follows:
 
 ```javascript
 /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
 const sidebars = {
-
   ...
-
-  for_developers: [
+  reference: [
     { type: 'category',
-      label: 'For Developers',
+      label: 'Reference',
       items: [
-        'for-developers/index',
-        'for-developers/ComponentDiagram',
-        'for-developers/foo', // <--- Your new page
-        'for-developers/ChainSync',
+        'reference/index',
+        'reference/foo', // <--- Your new page
+        ...
       ]
-
+    }
+  ]
   ...
+};
 ```
 
-The order of the page in the `items` list determines the order in which this entry will appear in the sidebar. See [`sidebars.js`](./sidebars.js) for the rationale behind not autogenerating this.
+The order of entries in the `items` list determines their placement in the sidebar. Refer to [`sidebars.js`](./sidebars.js) for the rationale behind manual sidebar configuration.
 
 # Building the website
 
-To install the packages required to build the documentation site run:
+To install the required packages for the documentation site, run:
 
 ```
 $ yarn
 ```
 
-After the necessary packages are installed by the above command, the
-documentation site can be built by running:
+After installation, build the documentation site by running:
 
 ```
 $ yarn start
 ```
 
-This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+This starts a local development server and opens a browser window. Most changes are reflected live without needing to restart the server.
 
 ## Build
 
+To generate static content:
+
 ```
 $ yarn build
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service.
+This command outputs the static content into the build directory, which can be hosted using any static content hosting service.
 
 ## Deployment
 
-We deploy the website using a GitHub action. See [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml).
+The website is deployed using a GitHub Action. See [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml).

docs/website/contents/explanations/consensus_protocol.md

@@ -0,0 +1 @@
+# Consensus Protocol

docs/website/contents/explanations/design_goals.md

@@ -0,0 +1 @@
+# Design Goals

docs/website/contents/explanations/ebbs.md

@@ -0,0 +1 @@
+# Epoch Boundary Blocks

docs/website/contents/explanations/genesis_design.md

@@ -0,0 +1 @@
+# Cardano Genesis

docs/website/contents/explanations/index.md

@@ -0,0 +1 @@
+# Introduction

docs/website/contents/explanations/ledger_interaction.md

@@ -0,0 +1 @@
+# Interaction with the Ledger Layer

docs/website/contents/explanations/managing_updates.md

@@ -0,0 +1 @@
+# Managing Updates

docs/website/contents/explanations/mempool.md

@@ -0,0 +1 @@
+# Mempool