lodestar
lodestar copied to clipboard
ChainSafe
Reconsider documentation website layout
Improve the current documentation website layout so that it is more palatable. Previous links will still need to be reacheable.
A potential list of top-level category could be (adapted from @philknows suggestions)
- Run a node
- Tooling/Libraries (includes light-client/prover)
- Lodestar Developer
A tentative deployment can be found here: https://jeluard.github.io/lodestar/
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
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
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/
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.
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.
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
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 -
@chainsafe/blst-ts -
@chainsafe/bls-keystore -
@chainsafe/bls-keygen -
@chainsafe/bls-hd-key
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.
@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.
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/ ?
No strong feeling from me, I would naturally put it under Contributing but both work.
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?
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:
- Installation
- Beacon Node CLI.
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.
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.
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
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.