Documentation Updates

[matthewkeil]

Problem description

We would like to update our documentation. We would like to foster communication between the team and the community to make sure the docs included all of the best and none of the rest!! 🥷

Solution description

We are researching the other client docs and will incorporate the most important sections from each to create a complete set of docs for Lodestar and the broader consensus client ecosystem.

Additional context

Lodestar Docs: https://chainsafe.github.io/lodestar Lighthouse Docs: https://lighthouse-book.sigmaprime.io/ Prysm Docs: https://docs.prylabs.network/docs/getting-started Teku Docs: https://docs.teku.consensys.net/ Nim Docs: https://nimbus.guide/

[matthewkeil]

Potential Layout

• Introduction

  • Proof-of-Stake
  • Consensus Clients
  • Ethereum Readings

• Getting Started

  • Installation
    • Install from Source
    • Using Docker
  • Creating a JWT
  • Block Exploration

• Beacon Management

  • Configuration
    • Available Flags
    • Using a Configuration File
  • Connecting to Peers
    • Firewall Management
    • NAT
    • ENR
  • MEV and Builder Management
  • Database
  • Syncing
    • Checkpoint Sync
    • Optimistic Sync
    • Historical Sync

• Validator Management

  • Configuration
    • Available Flags
    • Using a Configuration File
    • Proposer Settings File
  • Key Management
    • Fee Recipient
    • Key Recovery
    • External signer / Web3Signer
  • Withdrawals
  • Multiple and Fall-Back Validation

• Logging and Metrics

• Light Client

• Prover

• API

  • Making API calls
  • Using the debug API

• Troubleshooting

  • Common Installation Issues
  • Common Sync Issues
  • Common Validation Issues
  • Common Execution Layer Issues

• Supporting Libraries

  • libp2p
  • @chainsafe/libp2p-gossipsub
  • @chainsafe/ssz
  • @chainsafe/bls and @chainsafe/blst-ts

• Contribution

  • Bug Reports
  • Getting started
  • Repo Architecture
  • Testing
    • Unit Tests
    • Spec Tests
    • e2e Tests
    • Simulation Tests
    • Performance Tests
  • Submitting a PR

• Advanced Topics

  • Migrating from Other Clients
  • Slashing Protection
  • Setting up a Testnet
  • Doppelganger Detection
  • Weak Subjectivity

[matthewkeil]

Comments forwarded from discord by @wemeetagain:

• Install with Docker: lacking an example as in the 'Install from source' page -eg: docker run lodestar --help
• Validator management: lacking a section mentioning how to clear the lockfiles in case of a power outage, etc
• generally: consistency in style (use of 'eg:' vs 'ex:')
• Prometheus and Grafana: would be nice to include a screenshot of a working dashboard
• generally: Ensure urls are markdown links vs plaintext (see Prometheus and Grafana for an example of plaintext urls). markdown links need to be https://foo.com rather than just https://foo.com
• MEV Builder Integration: refresh stale introduction paragraphs
• Client monitoring: see if we can find a "specification" link that isn't a docs.google.com link
• Lodestar package structure: refresh graphviz graph node names

@wemeetagain would like to tackle typescript/javascript usage of lodestar packages

[wemeetagain]

• Related to API docs: https://github.com/ChainSafe/lodestar/issues/1060

[nflaig]

As suggested in the standup we could embed a API reference page (similar to CLI reference), I used redoc previously to do this and the results were pretty good, see Docker HUB API for an example.

This should be really easy to achieve once we know how to generate a openapi.json file which is already required by https://github.com/ChainSafe/lodestar/issues/1060. Redoc just needs a reference to the generated file (https://github.com/Redocly/redoc#tldr-final-code-example) and will generate everything from that. File should be ideally served from the same domain as the docs page itself.

[philknows]

New contributor guide/getting started section for developers: Examples:

• Add new API? What files do I need to update?
• How do I add a new network?

[philknows]

As discussed in Turkey, it makes sense to PR a documentation structure change to outline the docs better, then continuously contribute to updating the content within it. This way, we minimize issues with conflicts and rebasing your branch here https://github.com/ChainSafe/lodestar/tree/mkeil/redo-docs. The new structure contained within here are laid out much better and we can continuously update the content as we dedicate more time to making it more complete @matthewkeil .

[philknows]

As discussed on the March 5, 2024 standup, it was discussed that we would begin migration to Docusaurus for Lodestar docs due to its flexibility, React-based framework, and compatibility with current web technologies. It is important to note that this is not just platform change, but also an opportunity for us to vastly improve DevEx as described by some suggestions here: https://github.com/ChainSafe/lodestar/discussions/6493#discussioncomment-8632292

As part of migration we also need to figure out how to identify external links to our documentation and update as many to link the new doc URLs. From Github insights, the following traffic we can identify to our repo is:

• ethereum.org
  • https://ethereum.org/en/developers/docs/nodes-and-clients/light-clients/
• lodestar.chainsafe.io
• chainsafe.github.io (our current docs)
• beaconscan.com
• blog.ethereum.org
• dev.to
• Search engines:
  • google.com
  • search.brave.com
  • bing

As of today, our Google indexer shows the following external links to our documentation are:

Site	Linking pages	Target pages
ethereum.org	159	2
yarnpkg.com	56	2
npmjs.com	40	2
medium.com	29	2
github.com	28	2
ethstaker.cc	22	2
stratisevm.com	20	1
gnosischain.com	11	2
hackmd.io	11	2
earthether.org	10	1
libraries.io	10	2
twopercent.blog	7	1
jsdelivr.com	6	2
substack.com	5	2
devtool.tech	5	2
coincashew.com	5	2
socket.dev	4	2
0xzx.com	4	2
reddit.com	4	1
bloomblock.news	3	1
eigenlayer.xyz	3	1
cryptonxchange.com	3	1
baczek.me	3	1
axelar.com	3	1
mytokencap.com	3	1
opensourceagenda.com	2	2
blockex.ai	2	1
skypack.dev	2	2
xiaoc.cn	2	2
20bet-br.org	2	2
awesomeopensource.com	2	2
gerbil.education	2	1
chainsafe.io	2	2
gitbook.io	2	1
soos.io	2	1
odaily.news	2	1
ethereum-france.com	2	1
sigmaprime.io	2	1
okx126.com	2	1
tokentitansnews.xyz	2	1
gnosis.io	2	1
uucj.com	1	1
npm.io	1	1
wenjiangs.com	1	1
metasanjaya.com	1	1
ccvalue.cn	1	1
yzsam.com	1	1
nexofeed.com	1	1
bitpush.news	1	1
prylabs.network	1	1
nethermind.io	1	1
rocketpool.net	1	1
lido.fi	1	1
cryptocurrencyinn.com	1	1
jameuwu.com	1	1
questu.ru	1	1
promomatro.com	1	1
scortik.com	1	1
cryptovert.net	1	1
crypto-investissement.fr	1	1
yamisuke.com	1	1
cillionairee.com	1	1
blocknative.com	1	1
bibiqing.com	1	1
netlify.app	1	1
carbon-ratings.com	1	1
dailyblockchain.news	1	1
goudiewoodworking.com	1	1
codercto.com	1	1
snyk.io	1	1
blockchainhub.today	1	1
connect3.world	1	1
mifengcha.com	1	1
idevicehacked.com	1	1
u2e-free.cn	1	1
xord.com	1	1
defidaonews.com	1	1
mytoken.io	1	1
etherbreak.com	1	1
coinflash.co.uk	1	1
zjiakyz.com	1	1
wellgoll.com	1	1
packagegalaxy.com	1	1
pdfkitaplar.site	1	1
openstandia.jp	1	1

[philknows]

For some alignment on how other ChainSafe projects are setting up their Docusaurus pages, see https://handbook.chainsafe.io/development/documentation/