Deprecate `docs.substrate.io` plan
Opened this issue · 11 comments
URLs from substrate.io are quite useful and we suspect them to high a lot of traffic and clicks. But, most are not maintained, outdated, or wrong.
What we should do is:
- For all pages, include a fixed banner that indicates when this page was last edited. This should give a good idea if this page is already out of date or not.
- For pages that are going to have anew equivalent, add a banner that explicitly forward the user to the new page.
This is much better than a blanket redirect. A blanket redirect can be implemented in eg 1 year.
This is essentially step 5 as described here.
Here's the plan I have in mind to tackle this:
-
Add content specific banners to pages we know are outdated but we can point readers to the improved resource (e.g. like alluded to in the comments above, when Liam's storage migration ref docs are completed, point readers of https://docs.substrate.io/reference/how-to-guides/storage-migrations/basic-storage-migration/ and have a "The content of this page might have been deprecated by now, and the latest version is ... " type banner with relevant links.
-
Provide a guide so that anyone working on new reference docs (e.g. FRAME or devrel teams) can easily make a PR to update the relevant pages on docs.substrate.io to include the content specific banner. For e.g. how to format of the banner + if they wanted to see the changes in their local environment.
Will keep this updated with specific pages I know have more useful material in the rust docs, open to discussion but to kick it off:
- Storage migration stuff (point to ref docs when done cc @liamaharon) - these pages should point readers to the updated resource and/or delete the outdated content (https://docs.substrate.io/maintain/runtime-upgrades/#storage-migration and both pages here https://docs.substrate.io/reference/how-to-guides/storage-migrations/)
- FRAME Macro docs: https://docs.substrate.io/reference/frame-macros/ -> https://paritytech.github.io/polkadot-sdk/master/frame_support/attr.pallet.html
- Genesis build docs (https://docs.substrate.io/build/genesis-configuration/ -> https://paritytech.github.io/polkadot-sdk/master/frame_support/pallet_macros/attr.genesis_build.html)
- Weights docs: remove misleading guides about custom and conditional weights
After not being involved in docs.substrate.io content in 1.5 years these are the ones that off the top of my head I know have better, up to date material in the Rust docs.
I'm not sure what the plan is for pointing people to the master tutorial though (as per this issue's original name). What am I missing @kianenigma ?
Beyond just adding banners, I think it can't hurt to feel free to thin down (of simply remove) a lot of the content on these docs.substrate.io pages as we work our way to adding these deprecated notes.
Another thought but unsure about how valuable it may be is to add a banner there with a general warning about content being deprecated to the most visited pages on docs.substrate.io. On Simpleanalytics for e.g. this seems to be the Tutorials page (after the actual docs.substrate.io landing page from which most people use to get into the tutorials).
Update - banner would look like this:
- Pros: it's just html in the markdown, it's catchier than just using
>in markdown, requires just to copy paste the html snip and update the link - Cons: it's not sticky, readers only see it at the top of the page once
Because it's pretty catchy with the red color, I don't see the aforementioned con as being a blocker. Lmk if there's a dominant opinion against what I'm suggesting to do as a fix here.
I think it looks good, and doesn't need to be sticky.
Another thought but unsure about how valuable it may be is to add a banner there with a general warning about content being deprecated to the most visited pages on docs.substrate.io. On Simpleanalytics for e.g. this seems to be the Tutorials page (after the actual docs.substrate.io landing page from which most people use to get into the tutorials).
I think just saying something outdated without a replacement might be a bit of a turn off, but I would be open to it.
- Possibly, in all pages there could be a mild yellow warning of "hey, this might out of date, here is a better curated list of resources"
- In pages where we know what is the more up to date version, we link with the red banner.
Guide:
- (Optional) Follow the steps here to clone and run the docs.substrate.io site locally
- Make a PR to the page you want to warn readers about and copy paste this snip, adapting it to your needs:
<div class="warning">
<strong>⚠️ WARNING:</strong> This page contains outdated information. Please refer to the <a href="<new-link-here>">Rust docs</a> for the most up-to-date documentation on this topic.
</div>I think just saying something outdated without a replacement might be a bit of a turn off, but I would be open to it.
Let's stick to the yellow warning banner for now.
What are some other banners we need aka more updated docs that we can point docs.substrate.io readers to?
comment from @liamaharon: as soon as developer_hub is launched somewhere, we should also have a global banner that is forwarding people to the new version.
Would need to also have analytics at this point to monitor the traffic flow.
Is this issue about deprecating substrate.io or docs.substrate.io?
Is this issue about deprecating
substrate.ioordocs.substrate.io?
mainly docs.substrate.io, but I am 100% sure that the parent substrate.io should also be deprecated. In other words, the decision (big D) of removing substrate.io is already made. Although, the replacement for it will no longer be polkadot_sdk::developer_hub, but rather a new version of polkadot.network. Suggestions atm are dev.polkadot.network or polkadot.network/dev or polkadot.network/sdk.
Although, a page like this from the developer hub could be a short term replacement for this, but it is very crude.