IntersectMBO / IntersectMBO/ouroboros-consensus

Reorganize the documentation site

Open
#1,631 0 comments 0 reactions 1 assignee Claimed by @dnadales View on GitHub
documentation
Dominant language
Haskell
Stars
67
Forks
43
Avg merge
5d 13h
Merged PRs (30d)
43

Description

The current documentation site contains a mix of documents without a clear structure, making it hard to navigate and onboard new users.

We should reorganize the content using the [Diátaxis framework](https://diataxis.fr/), which classifies documentation into four categories: **Tutorials**, **How-To Guides**, **Reference**, and **Explanation**. This will help improve clarity, navigation, and content discoverability.

[This file](https://hackmd.io/UVd1tfaVQtOrHcK2xnPZaQ) contains the general roadmap for the documentation reorganization.

- [x] Review and classify existing documents.
- [ ] Restructure site layout based on Diátaxis.
- [ ] Update navigation and internal links.
- [ ] Adapt the existing documentation to the existing structure (this is an epic on itself).
- [ ] Write a section on the interaction with the ledger layer.
- [ ] Write a section on queries.
- [ ] Write a section on the interaction with the networking layer.
- [ ] Explain how version are negotiated.
- [ ] Write a section on the Consensus protocol.
- [ ] Write a section on the Mempool.
- [ ] Write a section on updating the Consensus layer (which includes the HFC).
- [ ] Write a section about the handling of time in Consensus (inspired by the [CivicTime](https://github.com/IntersectMBO/ouroboros-consensus/blob/5aac28bec41b7709f75a5c9f20e2431259cf237f/docs/website/contents/for-developers/CivicTime.md) document).
- [ ] Write a section on booting up the Consensus layer.
- [ ] Write a section on Storage Layer/ImmutableDB.
- [ ] Write a section on Storage Layer/VolatileDB.
- [ ] Write a section on Storage Layer/LedgerDB.
- [ ] Write a section on EBBs.
- [ ] Add a reference section about serialization.
- [ ] Add an SOP tutorial.
- [ ] Explain how cross-era forecasting works?
- Where is it implemented?
- How do we forecast when we cross into a new era?
- [ ] How do SOP telescopes assist in implementing cross-era translations?
- In particular we should mention [extendToSlot](https://github.com/intersectmbo/ouroboros-consensus/blob/fe64d327a89eb2966a8b599905db445f0ff7589a/ouroboros-consensus/src/ouroboros-consensus/Ouroboros/Consensus/HardFork/Combinator/State.hs#L222)
- Are telescopes used only for getHardForkState?
- [ ] Explain why we need `HeaderWithTime` (why we limit the use of time in Consensus).
- [ ] Add a better explanation on why we require update proposals to be approved `2 * stability windows` before the end of the epoch.
- [ ] Explain why diffusion pipelining requires `SelectView` to be totally ordered.
- [ ] Discuss how blocks from the future are handled.
- [ ] Add to the glossary: current selection.
- [ ] Add to the glossary: anchored prefix.
- [ ] Explain the block fetch protocol.
- [ ] Explain that time is divided into slots and that blocks are produced on those slots.
- [ ] Explain what VRFs are.
- [ ] Explain what nonces are and how they relate to VRFs.
- [ ] Explain what the active slot coefficient is.
- [ ] Explain what the stability window is.
- [ ] Explain grinding.
- [ ] Explain why we need `HardForkTxMeasure`.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.