Open Rashmirreddy opened 1 year ago
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:
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:
>
in markdown, requires just to copy paste the html snip and update the linkBecause 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.
See: https://github.com/substrate-developer-hub/substrate-docs/pull/2069
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.
Guide:
<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.io
ordocs.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.
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:
This is much better than a blanket redirect. A blanket redirect can be implemented in eg 1 year.