Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

New Substrate documentation released #1132

Open
NukeManDan opened this issue Jun 16, 2022 · 31 comments
Open

New Substrate documentation released #1132

NukeManDan opened this issue Jun 16, 2022 · 31 comments
Assignees

Comments

@NukeManDan
Copy link
Member

NukeManDan commented Jun 16, 2022

The Developer Hub documentation site has gone through a significant transformation.
If you have bookmarked pages in the old site, the page you are looking is most likely no longer available at that location.
This roadmap provides suggestions to help you navigate to the information you're looking for in the new site.

  • If you have bookmarked pages in the old site, the page you are looking for is no longer available at that location.

  • If you arrived here from a link within the new Substrate Developer Hub content, please open an issue to report the broken link.

  • If content is missing that was on the old docs, or otherwise is something you were looking for, please open an issue to let us know.

  • If you arrived at this page as the content you were looking for from a post on the Substrate and Polkadot Stack Exchange led you here, please suggest an edit on the post directly with the correct link in the new docs. If unable to do so, instead add a comment to notify the author and community that the location has changed. 🙏

  • If you arrived here from an external resource - such as a search engine, blog, example code, or other content that is maintained externally - please inform the authors that they need to update their links to use the new site.

  • If after searching the new docs, you cannot find what you need, please open an issue to request new or edited content and detail what you were looking for and mention if there was an external source that suggested it existed here or in the old docs.

New table of contents

Getting started

Key concepts

Runtime development

Tutorials

How-to guides

Tools

Advanced


📝 Let us know what you think!

Please provide feedback on you experience with the new docs!

Feel free to comment on this issue with any thoughts, comments for improvements or share what you like about the new docs experience! 😀

@565ee
Copy link

565ee commented Jun 22, 2022

i studying 05-private-network

https://github.com/substrate-developer-hub/substrate-docs/blob/main/v3/tutorials/05-private-network/index.mdx

but now , it disappear ! where is it ???

@lisa-parity
Copy link
Collaborator

lisa-parity commented Jun 22, 2022

It is split into two parts in the new site. Here is the tutorial using generated keys instead of the predefined account:
https://docs.substrate.io/tutorials/get-started/trusted-network/
If you want to start with the predefined accounts, you can find the updated tutorial here:
https://docs.substrate.io/tutorials/get-started/simulate-network/

@Azephiar
Copy link

Azephiar commented Jun 23, 2022

I'm looking for the 'Create your first Substrate blockchain' tutorial, where can I find it in the new docs?

@lisa-parity
Copy link
Collaborator

lisa-parity commented Jun 23, 2022

You can find the equivalent first blockchain tutorial here:
https://docs.substrate.io/tutorials/get-started/build-local-blockchain/

@rirotho
Copy link

rirotho commented Jun 23, 2022

I'm noticing some code differences between the old and new documentation version. Especially in Cargo.toml file and in some macros, like this one. Are you guys updating the Substrate node template too? Because the code in this new doc is slightly different. Thanks.
Screenshot from 2022-06-23 12-14-19
.

@didiermis
Copy link

didiermis commented Jun 24, 2022

Hey,
In previous days I did the first section of tutorials. Yesterday (june 22) I came back to finish the rest but for my surprise, documentation was updated. I'm learning substrate so I've been following the documentation these days. There's issues like:

  • Missing images
  • A lot of typo's
  • Dead links
  • Tutorials missing information/snippets/images/node-template versions missmatching.

I think you guys are still working on the site, I'm not complaining. Sorry if I can't link all the issues I found but I have little time to learn Substrate.

There's no coherence between Github/documentation/rust api documentation for the node basic template (as above comment mentioned) differs in various parts.

Tutorial are the ones in the worst state, I've been comparing both actual tutorial links and cache links from old documentation. I've spent a lot of time trying to fix them than learning the topic.

Tutorials from current documentation aren't working as intended, I was unable to complete the following:

  • Configure the Contracts pallet: Tutorial adds extra traits.
  • Monitor node metrics
  • Upgrade a running network
  • etc.

On the other hand, I LOVE the new structure of the documentation. The information is better organized. In the previuos version i was kinda lost when looking for a certain topic.

Is there news about the next release?

@MehranMazhar
Copy link

MehranMazhar commented Jun 24, 2022

https://docs.substrate.io/main-docs/fundamentals/runtime-intro/

In "FRAME" and "Composing a runtime with pallets" sections:
There is a line in which it is written "Image is missing"

@heymeowhero
Copy link

heymeowhero commented Jun 27, 2022

where is https://substrate.dev/recipes/ ???

@lisa-parity
Copy link
Collaborator

lisa-parity commented Jun 27, 2022

@joshuacheong
Copy link

joshuacheong commented Jun 28, 2022

This link is broken:
https://docs.substrate.io/tutorials/connect-other-chains/connect-to-evm/

As previously accessed, this tutorial illustrates how to build an Ethereum-compatible blockchain with Substrate using crates from the Frontier project.

@NukeManDan
Copy link
Member Author

NukeManDan commented Jun 28, 2022

EVM page was explicitly removed temporarily, as it has nothing to do with "connecting to other chains" - once a home for the page is decided, it will come back and appear in the nav as well 👍 (with a pass to polish the page, as it was "long in the tooth" as it stood)

@NukeManDan
Copy link
Member Author

NukeManDan commented Jun 28, 2022

@NukeManDan
Copy link
Member Author

NukeManDan commented Jun 28, 2022

I'm noticing some code differences between the old and new documentation version. Especially in Cargo.toml file and in some macros, like this one. Are you guys updating the Substrate node template too? Because the code in this new doc is slightly different. Thanks. !

@rirotho We are maintaining the node template, #1140 updated to the 0.9.24 version and I also updated tehe latest tag on templates to match. Please let us know if there are other issues, there could be discrepancies in code snippets here that were patched in the now archived version of the older site. Please open issues on each of these, or better, a PR to fix 😁

@flipchan
Copy link

flipchan commented Jun 28, 2022

What happen with the governance section? that displayed how to work with the democracy pallet and submit pre-images ? Is that part removed until new upgrades to the democracy pallet comes?

@MehranMazhar
Copy link

MehranMazhar commented Jun 28, 2022

@didiermis
Copy link

didiermis commented Jun 29, 2022

@lisa-parity
Copy link
Collaborator

lisa-parity commented Jun 29, 2022

@flipchan
Copy link

flipchan commented Jun 29, 2022

Is it possible that a sitemap can be created and submitted to google search console/be refereed to in robots.txt? So that the search engines index the correct sites and avoids dead links. Duckduckgo and other search engines are currently indexing and serving broken links and a sitemap would fix this
Screenshot_2022-06-29_22-32-34

@NukeManDan
Copy link
Member Author

NukeManDan commented Jun 29, 2022

#1193 - the reset is in the works now @flipchan and should remove old SE hits and trigger a crawl of the new content in the next few days.

https://docs.substrate.io/sitemap.xml

@doutv
Copy link

doutv commented Jul 1, 2022

I think it's annoying to move these existing tutorials to a new place.

I have written a few documents linking to these tutorials, and all these links are broken. I have to fix them by hand.

Maybe you can use a versioning system for docs.

e.g. https://docs.substrate.io/tutorials/v1
https://docs.substrate.io/tutorials/v2
https://docs.substrate.io/tutorials/v3

@lisa-parity
Copy link
Collaborator

lisa-parity commented Jul 1, 2022

@maemreyo
Copy link

maemreyo commented Jul 8, 2022

Hey I wanna find something related to Off-chain workers, but can not. How can I find? @lisa-parity

@lisa-parity
Copy link
Collaborator

lisa-parity commented Jul 8, 2022

@xue35
Copy link

xue35 commented Jul 20, 2022

Hi,

I am attending a course organized by Polkadot China. One assigned is to implment a 'Proof of Existance' by using substrate-node-template v3.0, and can refer to 'Proof of Existance' tutorial

However, the tutorial is now gone. Can you please help?

@lisa-parity
Copy link
Collaborator

lisa-parity commented Jul 20, 2022

Hi @xue35
The tutorial you are looking for is now here:
https://docs.substrate.io/tutorials/work-with-pallets/custom-pallet/
(or https://docs.substrate.io/tutorials/work-with-pallets/use-macros-in-a-custom-pallet/ depending on when the PR to change the name gets merged).

@hzy1919
Copy link

hzy1919 commented Aug 31, 2022

Hi, I suggest that some more Structure-Diagrams and Flow-Diagrams or other Diagrams can be added to the docs to explain more clearly .

@joshuacheong
Copy link

joshuacheong commented Aug 31, 2022

Hi, I suggest that some more Structure-Diagrams and Flow-Diagrams or other Diagrams can be added to the docs to explain more clearly .

I would agree but what areas do you need more visualizations for?

@hzy1919
Copy link

hzy1919 commented Aug 31, 2022

I would agree but what areas do you need more visualizations for?

IMO , such as:

  • The communication process between different types of nodes
  • Detailed processing of different types of nodes after receiving different messages
  • Diagrams of the different types of Tries and how they work
  • In unusual cases, how different types of nodes work
  • and so on ...

@lsgunnlsgunn
Copy link
Collaborator

lsgunnlsgunn commented Aug 31, 2022

Thanks very much for the suggestions. We're planning to add more diagrams (opportunistically) throughout the documentation. Appreciate your input on this!

@00hello
Copy link

00hello commented Sep 24, 2022

Half the new links in these comments are now broken too

@lisa-parity
Copy link
Collaborator

lisa-parity commented Sep 24, 2022

docs.substrate.io continues to evolve. If you are following this thread to locate topics, be forewarned that we have recently removed one level from the site hierarchy. For example:
what was "docs.substrate.io/main-docs/fundamentals/blockchain-basics/" is now "docs.substrate.io/fundamentals/blockchain-basics/"

Get started

  • Build a local blockchain shows you how to set up and interact with a local node in your development environment.
  • Simulate a network helps you simulate a two-node network using predefined accounts.
  • Add trusted nodes demonstrates how to generate keys and distribute a chain specification to create a small network of trusted validator nodes.
  • Authorize specific nodes illustrates how you can configure a network that has both authorized nodes and nodes with restricted access.
  • Monitor node metrics highlights how you can take advantage of the node metrics Substrate exposes.
  • Upgrade a running network illustrates forkless upgrades by modifying the runtime for a running Substrate node.

Work with pallets (first two links are the current names but are likely to change in the future)

Develop smart contracts (this section name is likely to change and that will change the URLs)

  • Prepare your first contract describes how to update your development environment and create a smart contract project using the ink! programming language.
  • Develop a smart contract demonstrates how to store, increment, and retrieve simple values using a smart contract.
  • Use maps for storing values extends the previous tutorial by illustrating how to use maps to store and retrieve values in a smart contract.
  • Build a token contract illustrates how you can build a simple smart contract for transferring ERC-20 tokens.
  • Troubleshoot smart contracts describes a few common issues that you might encounter when writing and deploying smart contracts.

Connect relay and parachains

Integrate with tools

  • Integrate a light client node describes how you can use the Substrate Connect light client node to synchronize and interact with a Substrate chain from a browser.
  • Access EVM accounts illustrates how you can use a customized Substrate node to access to Ethereum-based accounts and contracts.

Substrate Kitties is undergoing a major transformation, so it has not been republished. Stay tuned ...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests