owned this note
owned this note
Published
Linked with GitHub
---
type: slide
---
# Substrate Docs New Vision
> By Kian, April 2023, meant to be presented to the eng. team leads.
[Original braindump note](https://docs.google.com/document/d/14PM8Qm7TplI3hR-PaRXTGhBQ_QKJ1VYoCujE4t-nrZk/edit#)
---
## Polkadot Developer Community
Not so bad 🧐...
----
### StackExchange
| | Q | A | QA Ratio | Users | First Question |
|------------------------|------|------|----------|-------|----------------|
| Substrate and Polkadot | 3.5 | 3.9 | 85% | 3.1k | Feb 2022 |
| Ethereum | 51k | 56k | 67% | 105k | Jan 2016 |
| Solana | 2.8k | 3.1k | 80% | 4.5k | July 2022 |
| Cardano | 2.6k | 3.6k | 80% | 7.3k | April 2021 |
----
### Visits
----
### Visits
----
### Successful Parachains? 🥲
- Top 100: Polkadot
- Top 200: Kusama, Astar, Moonbeam, OriginTrail
- Top 300: EWT, Centrifuge
----
### But, Are We Improving? 📈
- Initial pool of tech-savvy folks is drained.
- Hard time getting into new builders from web2/Rust/non-Rust.
- Hard time getting partnerships and deals (improving, mostly outside of the scope).
> All f this can be improved by better documentation.
note:
all of this is just some random pieces of information that hopefully warrants more effort into our docs. Not all of them are bad though.
---
## Existing Order of Docs
- A mixture of articles that are:
- Often times **out of date** and don't even compile.
- Some amount of *duplicate information*, which only exacerbates this.
- Even if they do, they **don't form a single narrative** about what is the.
----
### Personal Anecdote
- Top PBA students have almost unanimously told me our docs suck.
note:
During PBA1, PBA2 and a few other places, I have asked a dozen times what people think about the docs, and in almost all cases:
* If they are versed enough, they realize it is bad, and learn from elsewhere.
* This is another show of sign that our ecosystem is only attracting alpha-developers, which might not always be the best business-developers!
* They are not versed enough to understand that it is bad.
---
## What Went Wrong?
1. Technical writes who don't have the context, trying to expand + reshuffle data around.
2. Lack of interaction/effort from core-devs.
- We merged significant PRs notifying anyone.
- Our external APIs are not perfectly documented.
---
## What We Can Do
1. Principles
2. Action Items
---
### Principles
- Some principles to guide the way.
- Anyone working on docs should understand and abide by these 🫡.
----
#### Ground Up 🔺
- If you can't back-reference, it sucks. The doc will either be too long, or lack context.
- If you can, it is awesome. You write less. One source of truth for everything.
- This starts with the **rust-docs**.
- Special tutorial about how to navigate it.
- FAQs in SE answered via rust-docs.
----
*What can be documented in a lower-level article, should be documented in a lower level article.*
note:
> This includes rust-docs as well. We should have a section that teaches you how to navigate docs.rs. Answer 10 common SE questions that could have been answered
> PBA Rust exam as an external resource. All of this is futile if the guy can't fucking code Rust.
> The requirement of back-referencing is to be VERY responsible with breaking existing URLs. See [call to stakeholders below](./##A Call to Stakeholders).
----
#### Less is More 🧘
- Only cover what we can deliver reasonably within 3-6 months.
- And we can maintain and keep up to date.
- Ink!? *external*.
- Deploy? *external*.
- XCM? *External!*
- What's a blockchain? *EXTERNAL* 🤬.
----
*What can be documented in an external article, should be documented in an external article.*
We should only cover things that are specific/opinionated to us.
----
#### Don't Repeat Yourself -- DRY 🪄
- Summarizing the above two:
*What has already been documented either externally or in a lower-level article, should not be documented again.*
- Example: Pallet documentation.
----
#### Aside: AI, GPT etc. 🤖
The combination of these should give us a strong core to build AI models on top.
- Strong core -> AI can ***multiply your efforts exponentially***.
- Weak core -> An army of technical writers cannot fix it.
> Our existing approach is slightly less work for a few, but a perpetual friction added to everyone else in the system, and a huge negative multiplier.
----
#### By Developers, For Developers 👩💻
- with ❤️
----
- For all the reasons mentioned, we need core-devs more engaged.
- bug-free-code is expectation, but somehow well-documented-code is not? 🤔
----
*What can reasonably be expected to be written by core-devs should be written by core-devs.*
----
#### Story > Facts 💌
- Form a narrative around **content** and **user journeys**.
- Low-level Content: ground up.
- User Journey: more tutorials, seeded from FAQ, and common scenarios.
---
### Recap: Principles
1. Ground Up 🔺
2. Less is More 🧘
3. Don't Repeat Yourself -- DRY 🪄
4. By Developers, For Developers 👩💻
5. Story > Facts 💌
---
### Contributions 💪🏻
1. The Content
2. The System
---
### The Content
- New Landing Page.
- Substrate/FRAME/Polkadot Master Tutorial.
- Improved Rust-docs
- "Ref-docs" for all the things left in between.
----
### The Content
* Deprecate everything in the existing docs.
* Mark with last-edited. Show warning, eventually redirect and remove from the internet.
* Everything new will be under a new URL.
note:
> We seem to be breaking URLs frequently. Isn't that a big big bad deal? Going forward we should not. This invalidates all the efforts being put into SE. If we don't have stable URL, one of our main principles of DRY cannot be enforced.
----
### Landing Page
```mermaid
%%{init: {'theme':'neutral'}}%%
flowchart LR
subgraph Onchain
ST[BUIDL] --> SC[Smart Contract]
SC --> Ink!
SC --> Solidity
subgraph Master Tutorial
ST --> R[WASM Runtime - FRAME]
R --> PARA[W Shared Security - Cumulus]
end
R --> SOLO[W/O Shared Security]
end
subgraph Offchain
ST --> UA[UApp - Smoldot]
UA --> CAPI
UA --> PJS[PJS API]
UA --> SubXT
SubXT
end
INT[Interoperability - XCM]
INT-..->SC
INT-..->R
INT-..->UA
```
note:
- subxt etc missing, onchain vs offchain.
- next steps at the end.
- react + rust cookbook as inspiration.
- "hyper using links" is also bad -- attention.
- splitting into parts + dopamine
- Substrate VS. Polkadot SDK should be settled first.
----
### Master Tutorial
```mermaid
%%{init: {'theme':'neutral'}}%%
flowchart LR
subgraph Backlinks
direction LR
subgraph internal
Ref[Reference Docs*]
end
subgraph Exteranl
Rest[Rest of Internet]
Polkadot[Polkadot Wiki]
Rust[Rust-docs]
end
end
subgraph .
direction LR
LP[Landing Page] --> ST
subgraph FRAME Master Tutorial
direction LR
ST[BUILD!] --> X1[Blockchain/Polkadot] --> X2[...] --> X3[STF] --> X4[Hooks] --> X5[Storage] --> X6[...] --> Cumulus[Cumulus Runtime]
end
end
%% X1 -.-> Backlinks
%% X2 -.-> Backlinks
%% X3 -.-> Backlinks
%% X4 -.-> Backlinks
%% X5 -.-> Backlinks
%% X6 -.-> Backlinks
%% Runtime -.-> Backlinks
```
---
### The System
- **Make sure written code remains up to date**: CI.
- **Make sure written text remains up to date**: "DevRel Audit" label.
note:
- key questions in each page/doc.
---
## Things I Cannot Do
- AI Engineer (DevRel? << **Outsourced**)
- Designer (Marcomms)
- Web owner (Marcomms)
- SEO, Backward compatible links
- CI system to build all code snippets continuously (CI/CD+DevRel).
note:
Web Owner:
- Deploy new landing pages, maintain URLs, create forwards, SEO optimization.
- A big part of the plan here is DRY. That responsible domain management such that links are not broken.
- For example, a big chunk of our links are going to http://paritytech.github.io/substrate/. If we ever break this, it will be a nightmare. Is anyone thinking about these things?
- Iggy!
---
## What's the Long Term Plan
- My role in docs is like Tinder in your phone, the sooner I am disposable, the better.
- All of my push to move more of the responsibility to core-devs is part my efforts to make this sustainable.
- I take more of the responsibility back home to me -> I leave less for the next gen docs team to maintain.
- I plan to stay involved in PBA+DevRel, and have high hopes for both.
---
## Beyond That Whole "Less is More" Thing
- My long term aspiration is translate the entire narrative of "**Blockchain -> Polkadot -> Substrate -> FRAME -> Cumulus -> XCM**" from PBA into some well-written format.
- A book, master tutorial v2, or similar...
Sign in with Wallet
