Reconsider documentation website layout

[jeluard]

Improve the current documentation website layout so that it is more palatable.
Previous links will still need to be reacheable.

[jeluard]

A potential list of top-level category could be (adapted from @philknows suggestions)

• Run a node
• Tooling/Libraries (includes light-client/prover)
• Lodestar Developer

[jeluard]

A tentative deployment can be found here: https://jeluard.github.io/lodestar/

[nflaig]

A tentative deployment can be found here: https://jeluard.github.io/lodestar/

I would prefer more content to be visible on the sidebar, and less nesting

[jeluard]

@nflaig So keep as what we have now?

[nflaig]

So keep as what we have now?

I like our current layout more, but we really need user feedback and maybe can get some insights with plausible on this.

Otherwise we will be changing things for the sake of changing it and hope for the best? sounds like a bad strategy

[jeluard]

Strategy was to make it persona oriented, with personas being roughly solo staker, lib user and contributor. Right now everything is flat which is confusing for any user IMO.

Note that nested item can be open by default (per item). I made a test in the test deployment showing this off: https://jeluard.github.io/lodestar/

[nflaig]

Right now everything is flat which is confusing for any user IMO.

Is it confusing or just makes things easier to find? This is how Lighthouse has it for a while https://lighthouse-book.sigmaprime.io/ and their docs are much more read than ours.

I am not for or against any layout, I just feel like we need to make more informed decisions.

[jeluard]

Nice! I would argue that they follow a more persona oriented hierarchy, albeit with more top-level elements :D I like the book oriented approach. It definitely should serve as inspiration for us.

[jeluard]

An alternate layout inspired by lighthouse one:

• Intro
• Getting Started
• Beacon Node
  • Data Retention
  • Security
  • Bootnode
  • Logging and metrics
• Validator
• APIs
  • Light Client and prover
• Advanced Topics
• Contributing
  • Supporting libraries
  • Tools
• FAQ

[philknows]

I made an alternative proposal after giving it some longer thought and the type of users we likely have coming into our documentation:

• Users (e.g. node runners, validators, researchers)
• Developers (e.g. TS devs using BLS modules, light client dev, integrators using our packages like the Prover, researchers building or modifying Lodestar)
• Contributors (e.g. People looking to contribute to the codebase + libraries)

Here's my proposal:

---

Home

docs/pages/contribution/getting-started.md

Run A Node

Goal: All information relating to running the Lodestar Beacon, Validator, Metrics, Bootnode

Quick Start

• Quickstart Scripts
• Quickstart Guide (import https://hackmd.io/@philknows/rJegZyH9q)

Installation

• Binaries
• Build from Source
• Docker
• Node Package Manager

Beacon Node

• Start a Beacon Node
• CLI Reference
• Data Retention
• Networking
• MEV and Builder Integration
• Syncing

Validator Client

• Stake with a Validator Client
• CLI Reference
• External Signer

Logging and Metrics

• External Client Monitoring
• Prometheus and Grafana

Discv5 Bootnode

• CLI Reference

---

Developer Tools

Goal: All information relating to builder tooling

Lodestar Light Client

• CLI Reference
• Usage

Lodestar Prover

• Usage

---

Supporting Libraries

Goal: All information relating to our JS/TS libraries for developers to utilize our modules effectively

BLS

• @chainsafe/bls
  • Documentation
• @chainsafe/blst-ts
  • Documentation
• @chainsafe/bls-keystore
  • Documentation
• @chainsafe/bls-keygen
  • Documentation
• @chainsafe/bls-hd-key
  • Documentation

Discv5

• Usage

LibP2P

• Usage

Serialization and Hashing

@chainsafe/SSZ

@chainsafe/persistent-merkle-tree

@chainsafe/as-sha256

---

Contributing

Goal: Give developers all the advanced tools and knowledge required
for developing on the Lodestar client or tooling

Advanced Topics

• Setup a Dev Testnet
• Setup a Multi-client Testnet
• Logging and Metrics (Advanced)

Dependency Graph

Development Tools

• Flame Graphs
• Heap Dumps
• Core Dumps

Testing

• Testing Overview
• E2E (End-to-End) Tests
• Integration Tests
• Performance Tests
• Simulation Tests
• Specification Tests

---

Tutorials

Goal: To persist step-by-step tutorials and guides for the most common uses of Lodestar

---

Frequently Asked Questions

Goal: To persist information that is frequently asked by users/developers and linking to the relevant conversations and issues.

[jeluard]

@philknows Sounds reasonable.

One comment: not sure I follow your point about Supporting Libraries. Right now it's just a list of libs ChainSafe wrote and are used by lodestar. In the context of lodestar, I don't think they matter much to end-users (whoever they are), so top-level seems confusing. At best, it can be useful for Contributors.
If the idea is to advertise those libs, not sure this is the right place. Adds too much confusion.

[philknows]

Would we prefer to just point/link users to the supporting library repos instead? Not all of them have actual documentation, at most a very basic readme.md. Or should we also use our Lodestar documentation for aiding developers looking to better understand our supporting libraries?

My preference is to have all of our documentation all in one place... but I understand if it can get too crowded. I see a bunch of developers only requiring specific pieces of our docs. Like someone who just wants to integrate BLS into their website. Or someone who wants to better understand SSZ usage. Should they go to ChainSafe/bls/docs or ChainSafe/ssz/readme? Or should all the info be contained within https://chainsafe.github.io/lodestar/ ?

[jeluard]

No strong feeling from me, I would naturally put it under Contributing but both work.

[jeluard]

@philknows note that your suggestion is pretty close to my original suggestion, still deployed

[nflaig]

I am not opposed to any of the proposed layouts, mostly concerned about making uninformed decisions without good data on who is even using our docs and for what audience we wanna optimize the layout.

Do we have data from the analytics yet?

[philknows]

Well we definitely need a baseline to keep working off of. In terms of analytics, we collect very minimal data about how people navigate and use our pages. Here's a view of the top pages visited and how long the average person spends on it. You can see where most people spend their time on our docs:

The goal of this issue IMO is just to have a v1 of our layout, implement it and continue to observe and make incremental improvements with more data over time. We can see the most useful portions of our docs really are:

1. Installation
2. Beacon Node CLI.

[nflaig]

We can see the most useful portions of our docs really are:

That's what I expected, the main audience are people running Lodestar (operators, solo stakers, etc.). We should have a layout that makes it as easy for them to find what they need. Our current layout does this already imo, but we can ofc restructure with keeping the data and main audience in mind.

[philknows]

That's what I expected, the main audience are people running Lodestar (operators, solo stakers, etc.). We should have a layout that makes it as easy for them to find what they need. Our current layout does this already imo, but we can ofc restructure with keeping the data and main audience in mind.

I'm more so looking to prep the docs to anticipate accommodating others who will stumble upon our docs if we capture other developers as part of our goals to expand adoption/usage of Lodestar. It won't drastically change what we already have that's currently catered to node operators/stakers/etc.

There are many users who use our libraries, arguably more than Lodestar itself. js-libp2p-noise as an example has over 5000 dependents and no real information or consolidated information on it. Providing more information, centralized and properly structured in one place for all types of users.

[nflaig]

js-libp2p-noise as an example has over 5000 dependents and no real information or consolidated information on it. Providing more information, centralized and properly structured in one place for all types of users.

We can have a centralized place to document those but I would expect developers using js-libp2p-noise to look at the README of the repo itself to find documentation on it

[philknows]

We can have a centralized place to document those but I would expect developers using js-libp2p-noise to look at the README of the repo itself to find documentation on it.

Definitely, I'm thinking longer-term when we get to expanding documentation for some of these libraries. I think there's also some synergistic coupling we can do with Lodestar and its libs knowledge in one place. It's easier IMO to have them all come to one central place of knowledge. You can already tell how outdated some of our library readmes are because there's no incentive to update it there either. For metrics capturing, it'll help us understand usage better and our value prop to the Ethereum JS ecosystem and not just consensus usage.