[☂️ Documentation] Umbrella ticket to update all-the-docs

Olshansk commented 8 months ago

Objective

Improve the poktroll docs to enable external contributors and 3rd party gateways.

Origin Document

The documentation in pokt-network/poktroll fell behind as development kicked off. The bar in pokt-network/pocket, and we want to get at least halfway there.

Goals

Create a better onboarding experience for anyone who comes by the pokt-network/poktroll repo.
Achieve "close to parity" with the prior "v1" repo
Enable 3rd party gateways to easily understand & integrate with Shannon TestNet
Share the development, work & research we have done with other projects in the ecosystem

Deliverables

[ ] [Everyone] Add missing architectural diagrams for this repo, where appropriate (new, migrated, etc...)
[ ] [Everyone] Move over diagrams from alpha repo
[ ] [@bryanchriswhite] Move over our best practices (code reviews, coding guidelines, etc..) from the v1
[ ] [@okdas] Make sure documentation related to DevNet, Telemetry & Observability is easily accessible
[ ] [@h5law] Add documentation related to the usage & integration of the SMT
[ ] [@red-0ne ] Provide documentation on the design and use of AppGate
[ ] [@RossiNYC] Identify which tool (e.g. GitBook, Docusaurus) we want to use to mirror our documentation in this repo.
[ ] [@Olshansk] Update the main entrypoint README

Creator: @Olshansk Co-Owners: @red-0ne @bryanchriswhite @okdas @h5law @RossiNYC

Olshansk commented 7 months ago

Sharing notes from a team meeting today o how we'll distribute some of the work on documentation:

[ ] @bryanchriswhite @Olshansk: choose a platform for docs to make them more discoverable (gitbook, docusaurus, etc...) and decide how it should be organized
[ ] @Olshansk: Update the main README, developer resources, onboarding, education, etc...
[ ] @Olshansk: High-level architecture (i.e. component diagram) showing the interaction between pocket actors, the DA layer, sequencers, etc...
[ ] @Olshansk: E2E Claim & Proof lifecycle (docs & sequence diagram)
[ ] @bryanchriswhite: RelaySessionManager + a few other /pkg (docs & component diagrams)
[ ] @bryanchriswhite + @red-0ne: E2E Relay Request & Response lifecycle (i.e. sequence diagrams)
[ ] @okdas: LocalNet Infra
[ ] @okdas: DevNet Infra
[ ] @okdas: Block explorer
[ ] @okdas: Observability, telemetry & Metrics
[ ] @h5law: Everything related to 💍
[ ] @h5law: How Shannon handles generic payloads
[ ] @h5law (review by @bryanchriswhite): Make sure depinject godocs are discoverable
[ ] @h5law (review by @red-0ne): appgatesever docs & component diagram
[x] @red-0ne - Config files for the supplier, application & gateway
[ ] @red-0ne - Gateway onboarding (SDKs, APIs, etc...)

Olshansk commented 7 months ago

@red-0ne Moving comment from #205 regarding config documentation for reference.

Staking configs:

App config -> for staking applications
Gateway config -> for staking gateways
Supplier config -> for staking suppliers

Operations configs:

AppGate config -> for operating a gateway or an application
RelayMiner config -> for operating a supplier

Olshansk commented 7 months ago

Been looking through some of the options and heavily leaning towards https://docusaurus.io/.

It'll require having a docs specific github repo, so we might need to migrate the docs from here to other to avoid some duplication, but seems to be the most common used lib across various projects and good for our usecase.

RossiNYC commented 7 months ago

@Olshansk - PNF already moving legacy POKT docs to Gitbook - wouldn't we just piggy back that? https://docs.pokt.network/

Olshansk commented 7 months ago

I looked around what some other projects are using and am finding Docusarus to be more common amongst technical teams (GROVE, Celestia, Lava, etc...).

I also asked ChatGPT for all the tradeoffs and the open-source nature of Docusarus + customizability (given that the protocol team is technical) is appealing.

I'm conflicted because I'm only considering GItBook (after some lightweight research) is because it's what PNF is using. Other than that I'd prefer to go with Docusarus. Eventually (no timeline right now), we could move PNF over too.

Wdyt?

--- ChatGPT Response ---

# GitBook vs Docusaurus Comparison

#### You:
What are the pros, cons & tradeoffsof Gitbook vs docusarus?

#### ChatGPT:
### GitBook vs. Docusaurus: Pros, Cons & Tradeoffs

#### GitBook

**Pros:**

- **User-Friendly Interface:** Intuitive UI, ideal for non-technical users.
- **Hosting & CDN:** Built-in hosting with CDN for faster content delivery.
- **Collaboration Features:** Real-time collaboration, similar to Google Docs.
- **Version Control:** Easy to manage documentation versions.
- **Integration Options:** Supports integration with various tools like Slack, GitHub.

**Cons:**

- **Limited Customization:** Less flexibility in customization compared to Docusaurus.
- **Cost:** Paid plans can be expensive for larger teams or more advanced features.
- **Limited Plugin Ecosystem:** Fewer plugins compared to Docusaurus, impacting extensibility.

**Tradeoffs:**

- **Ease of Use vs. Customization:** GitBook is more user-friendly but offers less customization than Docusaurus.
- **Integrated Hosting vs. Flexibility:** The convenience of built-in hosting trades off against the flexibility of self-hosting options like Docusaurus.

#### Docusaurus

**Pros:**

- **High Customization:** Highly customizable with React, allowing for unique designs.
- **Open Source:** Free and open-source, suitable for budget-conscious projects.
- **Robust Plugin System:** Extensive plugin ecosystem for enhanced functionality.
- **Markdown Support:** Strong Markdown support, beneficial for developers.
- **Static Site Generation:** Fast performance with static site generation.

**Cons:**

- **Requires Technical Knowledge:** More suitable for users comfortable with React and Markdown.
- **Self-Hosting Required:** You need to manage your hosting, which can be a hurdle for non-technical users.
- **Steeper Learning Curve:** The initial setup and customization require more technical understanding.

**Tradeoffs:**

- **Customization vs. Ease of Use:** Docusaurus offers more customization at the cost of a steeper learning curve.
- **Open Source vs. Support:** Being open-source, it might lack dedicated support unlike the commercial support available with GitBook.

In summary, your choice depends on the technical expertise of your team, the level of customization you need, and your budget. For non-technical users or teams prioritizing ease of use and collaboration, GitBook is preferable. For developer-centric teams that need extensive customization and are comfortable with self-hosting, Docusaurus is a more suitable choice.

Olshansk commented 2 months ago

Closing this out as we already have a large portion of the docs in place.

pokt-network / poktroll