Reorganize our documentation

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/explanation`](./contents/explanation))
+- **Tutorials** ([`contents/tutorials`](./contents/tutorials))
+- **HOWTOs** ([`contents/howtos`](./contents/howtos))
+- **Reference** ([`contents/reference`](./contents/reference))
 
-## 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/explanation`](./contents/explanation)), 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).