We need to overhaul our documentation, down to the information architecture level. Consider this a long-running tracking issue for a pretty big sub-project, potentially spanning across quarters.

Ultimately what we want is documentation that is user-centric, is useful and ultimately delightful to our users, and the Tendermint Core documentation has, up to now, been very sparse and occasionally cryptic.

To that end, my recommendation is first to break down the documentation by user type to allow folks easy entrypoints into the documentation. Each of the types of users we're targeting are as follows:

1. Application developers - i.e. ABCI developers
2. Operators - people who run validators, full nodes, seed nodes, etc.
3. Integrators - folks who integrate with our APIs/publicly exposed surfaces, like our RPC
4. Consensus engine developers - folks who have traditionally forked the consensus engine and tweaked it to their needs, or who have used our code as a library and depend on our Go APIs

There may be an additional type of "user" here that we haven't yet considered in-depth: researchers/academics.

Next, we should break each user type's documentation into 4 dimensions (where relevant, of course), inspired by the Diátaxis framework:

1. Tutorials
2. How-to guides
3. Explanation
4. Reference

If there's a better framework/approach, by all means please suggest it.

cc @adizere @alijnmerchant21

Definition of done

This issue can be closed when we're confident that we've at least structured our documentation well according to this framework, and is relevant to the releases we've made publicly available.

Follow-up work can include the addition of new tutorials, how-to guides, etc. as the system evolves, but that can be tracked in separate issues.

Sub-tasks

Please add sub-tasks here as you see fit, and feel free to reach out to team members and users to help populate this.

Docs folder

• Restructure the existing docs in the diataxis structure #1613

• Tutorials

  • Identify which types of tutorials would be most valuable for app developers

• How-to guides

  • Identify which types of how-to guides would be most valuable for operators

• Reference

  • docs: Per-release architecture as-is description #392