Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Restructure docs #125

Closed
matevz opened this issue Jun 14, 2022 · 3 comments
Closed

Restructure docs #125

matevz opened this issue Jun 14, 2022 · 3 comments
Assignees

Comments

@matevz
Copy link
Member

matevz commented Jun 14, 2022

The existing structure of the documentation was moved over from gitbook where it evolved organically over years. Consequently, some content is redundant across multiple chapters and some content should be moved to the website instead of docs (e.g. community and network primer chapters). The rule of thumb should be website should sell and entertain while documentation should educate people which are already convinced to use Oasis platform.

Documentation faces a standard audience VS products challenge, where the audience are:

  • users
  • node operators
  • dApp developers
  • core contributors.

And the products are (at least):

  • Emerald, Cipher, Sapphire ParaTimes
  • the Oasis network including Amber, Cobald, Damask upgrades
  • oasis-node, oasis CLI
  • oasis web and browser extension wallets
  • typescript and golang grpc clients
  • runtime SDK for rust
  • emerald web3 gateway, rosetta gateway, blockscout
  • ledger nano app

A product can have features corresponding to multiple audiences (e.g. Emerald or Cipher touches users - token transfers, node operators - running a paratime node, dApp developers - building dApps on them).

All docs changes must be backward compatible by adding static routes to the new URLs.

@matevz matevz self-assigned this Jun 14, 2022
@gw0
Copy link
Contributor

gw0 commented Jun 14, 2022

We also have a third "network" dimension (at least regarding versions and configuration) -- Mainnet and Testnet. The "Consensus layer" could also be thought of as a product.

I would argue that the "users" and "dApp developers" audiences should be split per-ParaTime, because the usage and development stacks for Emerald and Cipher are so drastically different there is not much in common.

My intuition would be to group around Consensus/Emerald/Cipher. For example:

  • Consensus layer: Rosetta gateway, Oasisscan Block Explorer, Oasis Monitor Block Explorer
  • Emerald ParaTime: Emerald usage tutorial (Metamask), Emerald dApp development tutorial (Truffle), Emerald Web3 gateway, Emerald Block Explorer (Blockscout)
  • Cipher ParaTime: Cipher usage tutorial, Cipher dApp development tutorial
  • Oasis Network: Mainnet/Testnet parameters with ParaTime config (e.g. Metamask settings), all upgrade instructions, gRPC endpoint usage tutorial (Typescript/Golang gRPC clients)

@tjanez
Copy link
Member

tjanez commented Jul 27, 2022

I think we should approach this incrementally, i.e. in evolutionary steps.

I think the first step is to split out the developer parts of our general docs into its own group using Docusaurus' Multiple sidebars feature.

@matevz
Copy link
Member Author

matevz commented Sep 12, 2022

Fixed in #200.

@matevz matevz closed this as completed Sep 12, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants