Quickstart redesign

[maoueh]

The quickstart section should become a real quickstart which should go directly to the point. From Platform independent Substreams, the content should change. We should give quick instructions how to build a Substreams from scratch. Here from that point a rough outline of what we envision:

• Create Substreams Manifest substreams.yaml

  Should give the pre-made manifest and quickly explain the important fields. The manifest should be defined minimally

• Create Rust Cargo.toml

  Content at https://substreams.streamingfast.io/getting-started/quickstart#crates-and-packages is already there. We just need to give a quick paragraph about important info about it mainly, the name of the project, the use of crate-type = ["cdylib"] so a WASM is generated, dependencies on substreams crates for helpers and on prost for protobuf encoding/decoding and profile.release to build an highly optimized .wasm file.

• Create proto/output.proto

  Quick overview that Substreams must output Protobuf encoded message. The message type should contains block's number, block's hash and block's parent hash

  Quick command to generate the code.

• Create src/lib.rs

  Quick code to map from Ethereum block to module's output.

• Execute

  Execution steps, validation and results.

• Next steps

  • Discuss the fact that substreams-template should be cloned when starting a new project.
  • Pointers to other materials.

Note The material we had that is more a tutorial like with greater details will be moved to a new page, will link the issue once available.

[seanmooretechwriter]

I did some research today for best practices and great examples of quickstart guides. These might be useful for recreating this quickstart and others in the documentation later.

https://spring.io/quickstart https://blog.readme.com/the-most-effective-api-quickstarts-in-8-examples/

Also, here is an example that Alex provided of Google's take on quickstart. It might make sense to adhere to their approach since the decision was made to follow the Google style guide for writing and documentation.

https://developers.google.com/calendar/api/quickstart/js

Lastly, I don't know if there is any desire to work at parity with The Graph documentation style but here is a quickstart from their system that might be useful as another model or example.

https://thegraph.com/docs/en/cookbook/quick-start/

Something that helps me is to create the outline first. These are the significant steps involved. Breaking those down into subtasks in the outline can also be helpful. It provides a roadmap for content creation and helps to make sure the vision of the content can be hardened before starting the more work-intensive tasks for writing code samples and explanations.

Here is the outline I see from the content provided above.

1. Create Substreams Manifest
2. Create Rust Cargo.toml
3. Create proto/output.proto
4. Create src/lib.rs
5. Execute
6. Next steps

Using this approach can also help keep the feel of the documentation consistent across examples, tutorial, READMEs and quickstarts. The sequence of steps, their names and starting and ending tasks should generally be consistent throughout a doc system or set of docs for many systems under the same umbrella.

[maoueh]

Agreed with all you said, I think you have a good understanding of what we want for the quickstart. There is no need to align with The Graph although inspiration to align with it is not a bad thing.

I reviewed The Graph quickstart, it's rather long from my point of view but the format, steps like format and low text centric is what we are looking for.

The outline is great, each section should have 1 to 2 paragraphs max, condensing the important pieces of information in quick sentence (You define your Substreams's name in field 'xxx' while this is there and that is here and so forth). Longer description should be left out and links to other documentation section should be used instead.

Seems we are aligned.

[seanmooretechwriter]

Thank you. This is great news. I'll circle back around to this task after we wrap up the sink tutorial and README.

[seanmooretechwriter]

Initial Quickstart redesign ready for review in the PR.

https://github.com/streamingfast/substreams/pull/141