Designing a Documentation Framework for Ethereum Nodes

This design was originally thought for trin, but I realized that it can extend to Ethereum nodes in general.

I'll base my design on docs I've found useful in the past: Reth and Lighthouse. I believe these are especially relevant as they are software similar to the Portal Clients. Additionally, I'll try to connect these designs with a more standardized approach: Diátaxis.

Diátaxis

This framework is based on the idea that technical documentation can be classified into four types:

• Tutorials: Tutorials are lessons that guide the reader through a series of steps to complete a project. Tutorials are learning-oriented.
• How-to Guides: How-to guides provide directions for readers to solve real-world problems step by step. How-to guides are goal-oriented.
• Reference: Reference guides offer technical descriptions of machinery and operational instructions. Reference material is information-oriented.
• Explanation: Explanation is a discussion that clarifies and illuminates a specific topic. Explanation is understanding-oriented.

While this framework doesn't specify the actual structure (where content should be placed), I believe it makes sense to keep these four types of documents separate.

Reth

Reth's documentation is available in three locations:

• The Reth Book
• reth/docs
• Within the code

The documentation in the book is primarily focused on users. It includes information on installing Reth, running a node, interacting with the network, and the output of all the --help commands of the CLI.

reth/docs contains information relevant to contributors. It covers details about the program's architecture, design, and the contribution process.

The other documentation is somewhat hidden. You need to download the repository and execute cargo doc --open. Other crates have their documentation on docs.rs. Although Reth also has docs published there, they appear to be outdated compared to locally built documentation. Specific information about certain aspects of the code is included here.

Lighthouse

Lighthouse's documentation can be found in The Lighthouse Book. Here, you can find information on using it (from installation to setting up a validator), details about the APIs, advanced usage guides, and information on how to contribute.

While Lighthouse features excellent in-code documentation, there are no documents published on docs.rs.

Attempting to Align Diátaxis with Existing Documentation

Let's start with the obvious: in-code comments/docs fulfill the reference role proposed by Diátaxis. They should be published to docs.rs or equivalent platforms for other languages.

The design and architecture documentation found in reth/docs can be considered explanations.

Tutorials and how-to guides are present in the books. However, the distinction between them is not very well defined.

My Proposal

I propose the following structure for documenting this kind of software:

• In-code reference
• User book / manual
  • Introduction / Content
  • Tutorials
  • How-to Guides
  • Further Reading
• Contributor book OR docs folder at the root of the repository
  • Introduction / Content
  • Tutorials
  • How-to Guides
  • Explanations
  • Reference

This structure allows for the separation of the four types of documentation proposed in Diátaxis, while maintaining related information together.

I encourage a clear distinction between documentation for users and for contributors. Users will rarely be interested in developer documentation. If I want to run a node, I likely won't be interested in learning how to write tests for the client I'm using.

Let's provide an overview of each part:

In-code Reference

This documentation is built with tools like cargo doc. It is written alongside the code and adheres to the principles of writing reference.

User Book / Manual

• Introduction: Offers context about the node and the book's contents.
• Tutorials: Contains materials to help users learn how to use the node. It serves as a starting point for new users, but advanced tutorials should also be developed.
• How-to guides: Features articles on using every feature of the node.
• Further reading.

This book does not include a reference section. We could maintain this approach or adopt what Reth does by incorporating the output of all --help commands.

Contributor Book

• Introduction: Offers context and content, similar to the other book.
• How-to guides: These guides will cover topics like setting up a development environment, writing tests, etc. They are closely related to the node but not useful for general users.
• Explanations: Explores concepts essential for understanding and contributing. This may include architecture, design choices, underlying protocols, etc. For instance, this article about Kademlia in the trin book.
• Reference: Provides quick information about the contribution process. For example, commands to run before pushing a commit, configuration settings for tools like Git, and the appropriate location for contributing documentation.

I've chosen not to include a tutorials section here. I don't believe there's anything particularly different about contributing to an Ethereum client. A tutorial here would cover general open-source contribution knowledge, and numerous well-written articles already cover this topic.