Rewrite Introduction section and Known issues section. (#1451)

Co-authored-by: olgahryniuk <[email protected]>

docs/docs/index.md

@@ -1,12 +1,16 @@
 # Welcome
 
-Hydra is a layer-two scalability solution for Cardano, which aims to increase
-the speed of transactions (low latency, high throughput) and minimize
-transaction cost.
+This section is a manual for users interested in running a Hydra node.
 
-This is the user manual for `hydra-node`, an implementation of the Hydra Head protocol, as originally published [here](https://eprint.iacr.org/2020/299.pdf). The `hydra-node` interfaces the Cardano blockchain, connects to other `hydra-node`s on a dedicated overlay network, runs a simplified (coordinated) Hydra Head protocol, and provides an API to clients.
+Hydra node is an implementation of the Hydra Head protocol, designed to enable fast and low-cost transactions by operating off-chain while leveraging the security of the main Cardano blockchain.
 
-:::warning Mainnet Availability disclaimer
+Decentralized applications (DApps), exchanges, and enterprise-level services can choose to run a Hydra node to participate in forming Hydra Heads – mini-ledgers that process transactions independently and in parallel, significantly enhancing throughput and reducing latency. 
+
+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
 mainnet, which means it is possible to run a `hydra-node` on mainnet using real
@@ -24,13 +28,13 @@ entirely at your own risk.
 You also acknowledge and agree to have an adequate understanding of the risks
 associated with use of the Hydra Head protocol version 0.10.0 or newer and that
 all information and materials published, distributed or otherwise made available
-on hydra.family and Hydra Github Repository is available on an ‘AS IS’ and ‘AS
+on hydra.family and Hydra GitHub repository is available on an ‘AS IS’ and ‘AS
 AVAILABLE’ basis, without any representations or warranties of any kind. All
 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, read more about the protocol [on the next page](./protocol-overview) or jump right in to [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/docs/known-issues.md

@@ -1,33 +1,30 @@
-# Known issues & limitations
+# Known issues and limitations
 
-Please be aware of the following known issues and limitations before running `hydra-node` on the Cardano `--mainnet`; as an incredibly technical project, Hydra in its current form requires an elevated level of understanding of the underlying infrastructure. Without the expertise required to operate a `hydra-node`, users may put their funds at risk if they are unfamiliar with the implementation and usage process.
+Before running a Hydra node on the Cardano mainnet, it is important to be aware of several known issues and limitations. Operating a Hydra node requires a deep understanding of the underlying infrastructure, and you may risk your funds if you are unfamiliar with the implementation and usage processes.
 
 ### Head protocol limits
 
-As transaction sizes and execution budgets are limited on Cardano:
+Due to the limitations on transaction sizes and execution budgets on Cardano, the Hydra protocol has the following constraints:
 
-- The protocol can only handle a maximum number of participants in a Head (see [cost of collectcom transaction](/benchmarks/transaction-cost/#cost-of-collectcom-transaction)). Upon startup, the `hydra-node` will inform you of the current configured maximum when trying to configure too many peers.
+- The protocol can only handle a maximum number of participants in a head see [the cost of CollectCom transaction](https://hydra.family/head-protocol/unstable/benchmarks/transaction-cost/#cost-of-collectcom-transaction). When attempting to configure too many peers, the Hydra node will inform you of the current configured maximum.
 
-It's currently possible to be denied access to funds by other protocol participants at various stages in a Hydra Head because of the complexity or size of the UTxO being committed or created while the Head is open:
+Currently, participants may be denied access to their funds by other protocol participants at different stages within a Hydra head because of the complexity or size of the UTXO being committed or created while the head is open:
 
-- The head cannot be _finalized_ if holding more than ~80 assets (see [cost of fanout transaction](https://hydra.family/head-protocol/benchmarks/transaction-cost/#cost-of-fanout-transaction) for latest numbers), although it can be _closed_
-- Tokens minted and not burnt in an _open_ head will prevent it from being _finalized_
-- If one or more participants commit UTxO too large to be processed together in a `CollectCom` or `Abort` transaction, the Head will be stuck in the _initialising_ stage
+- The Hydra head cannot be _finalized_ if it holds more than approximately 80 assets (see [the cost of FanOut transaction](https://hydra.family/head-protocol/benchmarks/transaction-cost/#cost-of-fanout-transaction) for latest numbers), although it can be _closed_
+- Tokens that are minted and not burned within an open Hydra head will prevent the head from being _finalized_
+- If one or more participants commit UTXOs that are too large to be processed together in a `CollectCom` or  `Abort` transaction, the Hydra head will remain stuck in the _initialising_ stage.
 
-There are couple of items in the roadmap around reducing the risk of locking up funds in a Hydra Head:
+See these resources for additional information about reducing the risk of locking up funds in a Hydra head:
 
-- [Directly open heads](https://github.com/input-output-hk/hydra/issues/1329)
-- [Always abortable Head](https://github.com/input-output-hk/hydra/issues/699)
-- [Limit size/complexity of UTxOs in the Head](https://github.com/input-output-hk/hydra/issues/698)
-- [Only sign closable snapshots](https://github.com/input-output-hk/hydra/issues/370)
+* [Directly open heads](https://github.com/input-output-hk/hydra/issues/1329)
+* [Always abortable head](https://github.com/input-output-hk/hydra/issues/699)
+* [Limit size/complexity of UTXOs in the head](https://github.com/input-output-hk/hydra/issues/698)
+* [Only sign closable snapshots](https://github.com/input-output-hk/hydra/issues/370)
 
 ### Training wheels
 
-- There is a hard-coded limit on **mainnet** network where you can
-  only commit up to 100 ADA into the Hydra head. This is only a safety
-  precaution and is going to be increased as we gain more experience
-  in running Hydra heads on the mainnet.
-
+There is a hard-coded limit on the **mainnet** where only up to 100 ada can be committed into the Hydra head. This is a safety precaution and will be increased as more experience is gained in running Hydra heads on the mainnet.
+
 ### Known bugs
 
-Refer also to the project repository issue tracker for [known issues](https://github.com/input-output-hk/hydra/issues?q=is%3Aissue+is%3Aopen+label%3A%22bug+%3Abug%3A%22) with the code. Should you discover any security relevant problems, please follow our [security policy](https://github.com/input-output-hk/hydra?tab=security-ov-file#readme).
+Refer to the project repository issue tracker for [known issues](https://github.com/input-output-hk/hydra/issues?q=is%3Aissue+is%3Aopen+label%3A%22bug+%3Abug%3A%22). If you discover any security-relevant problems, please follow our [security policy](https://github.com/input-output-hk/hydra?tab=security-ov-file#readme).