V2 docs
Feature Description
Following on #32, we decided that a collection of interlinked pages will be the best structure to reflect the ongoing development and the many facets of the fathom project.
This will be a collection of different pages, each addressing a particular aspect of the fathom protocol. By using links and index-pages at the end of each page, users will be able to quickly learn the aspects about fathom that they care about.
Each page will describe its
- audience (what does the reader want to learn)
- content (what will he learn)
- prerequisites (what should the reader know to make sense of the page)
- Read-next selection of links at the end that explores different related aspects
Motivation
This goes away from trying to find one-linear reading experience to suit everyone and towards some explorable-explanation-type-documentation. It will allow us to easily introduce new aspects without having to break existing documentation and should be easy to develop and maintain.
Further possible elements could be:
- Pop-up-elements,
- texts-on-hover,
- foldable textboxes behind a "go-deeper"-symbol,
- simulations,
- labels for pages (cryptoeconomics, small communities, long/short-term, ...)
- links to code
- suggestion-box at the end (but what about...?)
Possible Implementation
TBD ideally, the used framework does not force us to introduce too many specific elements into the text and allows us to extend it in the future.
Observation
It will be a challenge to find the right way to start. What are the first aspects, abstract views of fathom the reader sees. How abstract do we want to go? (Wild-idea: start with one line only!)
Checklist
-
Compile list of possible pages -
Write the scaffold of pages -
Decide on framework and implement a clickable prototype