Remove core concepts

CHANGELOG.md

@@ -20,6 +20,8 @@ changes.
 
 - Change `--start-chain-from` to always use the newer point when also a head state is known.
 
+- Moved several pages from "core concepts" into the user manual and developer docs to futher improve user journey.
+
 ## [0.17.0] - 2024-05-20
 
 - **BREAKING** Change `hydra-node` API `/commit` endpoint for committing from scripts [#1380](https://github.com/input-output-hk/hydra/pull/1380):
@@ -446,7 +448,7 @@ head again.
 - Add the
   [specification](https://github.com/input-output-hk/hydra/tree/master/spec) to
   the repository and
-  [website](https://hydra.family/head-protocol/core-concepts/specification).
+  [website](https://hydra.family/head-protocol/dev/specification).
   [#693](693)
 
 - Disabled `aarch64-darwin` support, until a `cardano-node` for this platform is
@@ -611,7 +613,7 @@ Only when this procedure has been applied to all Hydra nodes can you open a new
 
 - After restarting `hydra-node`, clients will receive the whole history.  [#580](https://github.com/input-output-hk/hydra/issues/580)
   + This history will be stored in the `server-output` file in `--persistence-dir`.
-  + Clients should use `Greetings` to identify the end of a [restart/replay of events](https://hydra.family/head-protocol/core-concepts/behavior#replay-of-past-server-outputs).
+  + Clients should use `Greetings` to identify the end of a [restart/replay of events](https://hydra.family/head-protocol/docs/api-behavior#replay-of-past-server-outputs).
 
 - Fixed observing the chain for Hydra L1 transactions after restart. [599](https://github.com/input-output-hk/hydra/issues/599)
 
@@ -733,9 +735,9 @@ Only when this procedure has been applied to all Hydra nodes can you open a new
   + Not crash anymore on rollbacks
   + Rewind the internal head state to the point prior to rollback point
   + Added `RolledBack` server output, see [API reference](https://hydra.family/head-protocol/api-reference)
-  + See the [user manual](https://hydra.family/head-protocol/core-concepts/rollbacks/) for a detailed explanation on how rollbacks are handled.
+  + See the [user manual](https://hydra.family/head-protocol/dev/rollbacks/) for a detailed explanation on how rollbacks are handled.
 
-- [Hydra Network](https://hydra.family/head-protocol/core-concepts/networking) section on the website about networking requirements and considerations
+- [Hydra Network](https://hydra.family/head-protocol/dev/networking) section on the website about networking requirements and considerations
 
 - [Benchmarks](https://hydra.family/head-protocol/benchmarks) section on the website with continuously updated and published results on transaction costs of Hydra protocol transactions
   + These are also performed and reported now on every PR -> [Example](https://github.com/input-output-hk/hydra/pull/340#issuecomment-1116247611)

docs/core-concepts/behavior.md → docs/docs/api-behavior.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 5
----
-
 # API Behavior
 
 :::caution Deprecated

docs/docs/dev/index.md

@@ -8,4 +8,4 @@ So you already read the [User Manual](../index.md) and still want to learn more
 
 The developer documentation can help you with that. It is a collection of materials expanding on _using_ into _understanding_ Hydra. It is aimed anyone wanting to get a deeper understanding of the Hydra protocol, protocol architects who want to build their own variants and of course developers who contribute to the [reference implementation](https://github.com/input-output-hk/hydra) of Hydra itself.
 
-Consequently, the following sections are more technical and maybe not as cohesive as the user manual, but the [architecture](./architecture) or the [specification](/core-concepts/specification) should be a good starting point.
+Consequently, the following sections are more technical and maybe not as cohesive as the user manual, but the [architecture](./architecture) or the [specification](./specification) should be a good starting point.

docs/core-concepts/layer-two.md → docs/docs/dev/layer-two.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 3
----
-
 # Layer 2 solutions
 
 This section provides an overview of various types of layer 2 solutions, along with several examples.

docs/core-concepts/scalability.md → docs/docs/dev/scalability.md

@@ -1,7 +1,3 @@
----
-sidebar_position: 2
----
-
 # Scalability
 
 Decentralized systems, including blockchains, face fundamental scalability limitations due to their reliance on global transaction replication to ensure security. This constraint is commonly known as the blockchain trilemma, where _decentralization_, _security_, and _scalability_ counteract each other. Although Cardano employs an efficient consensus algorithm, its global distribution among thousands of block-producing nodes results in block creation approximately every twenty seconds. During peak transaction times, this can lead to increased settlement times as transactions may not be included in the immediate next block.

docs/core-concepts/specification.md → docs/docs/dev/specification.md

@@ -1,8 +1,3 @@
----
-sidebar_position: 6
-custom_edit_url: https://github.com/input-output-hk/hydra/tree/master/spec
----
-
 # Specification
 
 The specification is currently written in LaTeX and can be [edited](https://github.com/input-output-hk/hydra/tree/master/spec) in the Hydra repository. You can view the rendered version below or download it for fullscreen viewing [here](/hydra-spec.pdf).

docs/docs/faqs.md

@@ -1,3 +1,6 @@
+---
+title: FAQ
+---
 # Frequently asked questions
 
 <details>

docs/docs/index.md

@@ -8,8 +8,6 @@ Decentralized applications (DApps), exchanges, and enterprise-level services can
 
 The `hydra-node` interfaces with the Cardano blockchain, connects to other `hydra-nodes` on a dedicated overlay network, runs a simplified (coordinated) Hydra Head protocol, and provides an API for clients.
 
-Navigate through tutorials and documentation guides to get started. If you want to learn more about core concepts, see [this section](https://hydra.family/head-protocol/core-concepts). If you're interested in building, see [developer documentation](https://hydra.family/head-protocol/docs/dev).
-
 :::warning Mainnet availability disclaimer
 
 The Hydra Head protocol version 0.10.0 or newer is compatible with the Cardano
@@ -34,7 +32,7 @@ implied terms are excluded to the fullest extent permitted by law. For details,
 see also sections 7, 8 and 9 of the [Apache 2.0 License][license].
 :::
 
-Now, without further ado, you can learn more about the protocol by visiting the [protocol overview page](/core-concepts/protocol-overview) or directly dive into [getting started using a local devnet](./getting-started).
+Now, without further ado, you can learn more about the protocol by visiting the [protocol overview page](./protocol-overview) or directly dive into [getting started using a local devnet](./getting-started).
 
 [known-issues]: ./known-issues.md
 [license]: https://github.com/input-output-hk/hydra/blob/master/LICENSE

docs/core-concepts/protocol-overview.md → docs/docs/protocol-overview.md

@@ -1,8 +1,4 @@
----
-sidebar_position: 4
----
-
-# Hydra Head protocol overview
+# Protocol overview
 
 Hydra is the layer 2 scalability solution for Cardano, designed to increase transaction speed through low latency and high throughput while minimizing transaction costs. [Hydra Head](https://eprint.iacr.org/2020/299.pdf) is the first protocol of the Hydra family that lays the foundation for more advanced deployment scenarios using isomorphic, multi-party state channels. For an introduction to the protocol, refer to these two blog posts: 
 

docs/docusaurus.config.js

@@ -75,17 +75,6 @@ const config = {
         sidebarPath: false,
       }),
     ],
-    [
-      "content-docs",
-      /** @type {import('@docusaurus/plugin-content-docs').Options} */
-      ({
-        id: "core-concepts",
-        path: "core-concepts",
-        routeBasePath: "core-concepts",
-        editUrl,
-        editLocalizedFiles: true,
-      }),
-    ],
     [
       "content-docs",
       /** @type {import('@docusaurus/plugin-content-docs').Options} */
@@ -165,11 +154,6 @@ const config = {
             label: "Developer Documentation",
             position: "left",
           },
-          {
-            to: "/core-concepts",
-            label: "Core Concepts",
-            position: "right",
-          },
           {
             to: "/topologies",
             label: "Topologies",

docs/sidebars.js

@@ -1,43 +1,24 @@
 module.exports = {
   userDocumentation: [
-    {
-      type: "doc",
-      label: "Welcome",
-      id: "index",
-    },
+    "index",
+    "protocol-overview",
     "known-issues",
     {
       type: "html",
       value: "<small><b>Tutorials</b></small>",
       defaultStyle: true,
       className: "sidebar-header",
     },
-    {
-      type: "doc",
-      id: "getting-started",
-      label: "Getting started",
-    },
-    {
-      type: "doc",
-      id: "tutorial/index",
-      label: "Open a head on testnet",
-    },
+    "getting-started",
+    "tutorial/index",
     {
       type: "html",
       value: "<small><b>Documentation</b></small>",
       defaultStyle: true,
       className: "sidebar-header",
     },
-    {
-      type: "doc",
-      id: "installation",
-      label: "Installation",
-    },
-    {
-      type: "doc",
-      id: "configuration",
-      label: "Configuration",
-    },
+    "installation",
+    "configuration",
     {
       type: "category",
       label: "How to ...",
@@ -50,11 +31,7 @@ module.exports = {
         },
       ],
     },
-    {
-      type: "doc",
-      id: "faqs",
-      label: "FAQ",
-    },
+    "faqs",
     {
       type: "html",
       value: "<small><b>Reference</b></small>",
@@ -69,8 +46,9 @@ module.exports = {
     {
       type: "link",
       href: "/api-reference",
-      label: "API reference",
+      label: "API Reference",
     },
+    "api-behavior",
     {
       type: "link",
       href: "/benchmarks",
@@ -79,10 +57,34 @@ module.exports = {
   ],
 
   developerDocumentation: [
+    "dev/index",
+    {
+      type: "doc",
+      id: "dev/specification",
+      label: "Specification",
+    },
+    {
+      type: "category",
+      link: { type: "doc", id: "dev/architecture/index" },
+      label: "Architecture",
+      items: ["dev/architecture/networking"],
+    },
+    "dev/rollbacks/index",
+    {
+      type: "html",
+      value: "<small><b>Background</b></small>",
+      defaultStyle: true,
+      className: "sidebar-header",
+    },
+    "dev/scalability",
+    "dev/layer-two",
     {
-      type: "autogenerated",
-      dirName: "dev",
+      type: "html",
+      value: "<small><b>Reference</b></small>",
+      defaultStyle: true,
+      className: "sidebar-header",
     },
+    "dev/haskell-packages",
     {
       type: "link",
       href: "/adr",

docs/standalone/audit-guidelines.md

@@ -117,7 +117,7 @@ This sections gives a detailed description of the artifacts mentioned above in t
 
 The Hydra Head protocol implementation derives from [Hydra: Fast Isomorphic State Channels](https://eprint.iacr.org/2020/299.pdf) in several ways. Especially some simplifications have been introduced and generalizations removed.
 
-The [Hydra Head specification](/core-concepts/specification) captures these deviations and also includes the "formal notation" of the actual transaction constraints (which are foregone in the original paper). Also, it details the L2 protocol logic for the **Coordinated** Head protocol - which is implemented in V1.
+The [Hydra Head specification](/docs/dev/specification) captures these deviations and also includes the "formal notation" of the actual transaction constraints (which are foregone in the original paper). Also, it details the L2 protocol logic for the **Coordinated** Head protocol - which is implemented in V1.
 
 ### Artifact 2: Hydra Head Protocol Implementation
 

docs/topologies/index.md

@@ -5,7 +5,7 @@ sidebar_position: 1
 
 # Topologies
 
-Hydra Head is a well-defined Layer 2 consensus protocol as explained in the [Core Concepts](/core-concepts) page, but this is not the end of the story and does not really define _how to use_ this protocol and what _topologies_ are possible. While [example use cases](/use-cases) should help in understanding the former, the _topologies_ below explain some of the various ways in which Hydra Nodes and Hydra Heads could be deployed and interconnected.
+Hydra Head is a well-defined Layer 2 consensus protocol as explained in the [Developer documentation](/docs/dev), but this is not the end of the story and does not really define how to use this protocol at large and what _topologies_ are possible. While [example use cases](/use-cases) should help in understanding the former, the _topologies_ below explain some of the various ways in which Hydra Nodes and Hydra Heads could be deployed and interconnected.
 
 As more users implement solutions on top of Hydra, this "catalog" of topologies shall expand to help newcomers find and build the deployment model that suits best their use case.
 
@@ -15,4 +15,4 @@ import DocCardList from '@theme/DocCardList';
 import {useDocsSidebar} from '@docusaurus/theme-common/internal';
 
 <DocCardList items={useDocsSidebar().items.filter(({ docId }) => docId != "index")}/>
-```
+```

hydra-node/json-schemas/api.yaml

@@ -10,7 +10,7 @@ info:
     For example if client provides a path that looks like this `/?history=no&snapshot-utxo=no` the server will not serve prior history of server outputs, and the utxo field in the json will be omitted.
 
     They can interact with their node by pushing events to it, some are local, and some will have consequences on the rest of the head.
-    See [the documentation](https://hydra.family/head-protocol/core-concepts/behavior/) for more details on the overall API behavior.
+    See [the documentation](https://hydra.family/head-protocol/dev/api-behavior/) for more details on the overall API behavior.
 
     Users can also use the HTTP endpoint to draft a commit tx using their own utxo, potentially including a blueprint tx as part of the draft.
 

hydra-node/json-schemas/logs.yaml

@@ -950,7 +950,7 @@ definitions:
           'contents' field. Please note each possible precondition
           failure is tied to some specific 'require p' expression in
           the specification (check
-          https://hydra.family/head-protocol/core-concepts/specification).
+          https://hydra.family/head-protocol/dev/specification).
         additionalProperties: false
         required:
           - tag