Guide refactoring

[AlianBenabdallah]

Summary

This issues proposes a new design for the guide. The main directions are to give more visibility to the prometheus metrics and push low level details to the end of the guide. The goal is to facilitate the onboarding experience of new users and to push them to use all the features we propose. This guide will also make use of Grafana to monitor hermes.

Requirements

• Hide low level details.

  • Features section should be at the end
  • REST API should be at the end
  • Telemetry should be at the end
  • Example configuration should contain a minimal example. A detailed description of every parameter should be at the end.

• Use metrics in the tutorials.

  • Provide a Grafana template for tutorials.
  • Refer to these metrics to show that a packet was (in)correctly relayed.

• Explain how metrics can be useful. ([#2520](Update telemetry documentation and metric names/descriptions #2520))

• Deploy multiple instances of Hermes in an example.

  • Explain the requirements.
  • Explain why it can be worth it to deploy multiple instances of Hermes.
  • Provide a Grafana (+Loki) template for this case as well.

• Deploy Hermes in production (on real blockchains).

  • Show where to find the address of an RPC/GRPC endpoint.
  • Show how to set the gas params.
  • Show how to use packet filters and why they can be important for real blockchains.
  • DO NOT CREATE CHANNELS.

• Troubleshooting.

  • List common issues and provide way to avoid them / fix them.
  • Some errors can be complex and should be documented as well.
  • Note : Some issues can be difficult to notice.

• Cleanup of tx raw content.

  • #[2522](Release Hermes v1.0.0.rc-2 #2522) deletes this section but it could potentially be moved somewhere else.
  • Section Identifiers can be confusing (usage of tx raw / create client)

• Add links to educational resources explaining what a command does.

  OR

• Add diagrams.

  • Users should understand what their actions trigger.

• Relationship between Client/Connection/Channel

  • Explain that you need to first open a client, then a connection then a channel.
  • Explain how and why it is possible for multiple channels to share a connection.
  • Explain how and why it is possible for multiple connections to share a client.
  • Explain how and why it is possible to have multiple clients tracking the same chain.

Proposal

1. Introduction

   Hermes Overview + “Where to go” section ([example](https://spark.apache.org/docs/latest/index.html#where-to-go-from-here)) + Link to FAQ Page + Glossary

2. Quick start

   • Pre-requisites
   • Installation (push users to build from source if they want to follow the tutorials)

3. Tutorials

   • Relay on two local chains
     • Initial setup (2 chains + Grafana)
     • Create channels / relay
   • Even more local chains
     • Initial setup (3+ chains), no grafana
     • Create channels (diagram of the topology)
     • Relay
   • Relay in production
     • Set up + Grafana
     • Relay packets
   • Deploy multiple instances of Hermes

4. Advanced

   • Features
   • Troubleshooting : (Health check command + inspecting relayer state + connecting to a FN protected by HTTP basic + log command + profiling…)

5. Documentation :

   • Configuration
   • Telemetry
   • REST API
   • Commands

6. Help

7. Glossary

Educational resources

What is IBC? | Cosmos Developer Portal

Video : Hermes Relayer - Connecting IBC enabled chains - YouTube

Acceptance Criteria

---

For Admin Use

• Not duplicate issue
• Appropriate labels applied
• Appropriate milestone (priority) applied
• Appropriate contributors tagged
• Contributor assigned/self-assigned