seanmooretechwriter
commented
1 year ago Hey Alex,
I believe you addressed all of these. Can you please confirm and we'll close this one out?
Part of the reason I'd broken those pages up is for SEO and it's also what the GitBook documentation recommended. Just so you know why.
maoueh
Each header is a general comment that might require further discussions
Prerequisites
prerequisites: this page says “myriad technologies”.. there’s no benefit in having multiple techs, it’s rather scary. Let’s say “uses a few technologies”, and highlight ease of use. Something like: “Substreams leverages powerful technologies, including:”
the phrase “Substreams can be used by blockchain, subgraph, Rust, JavaScript, Python, and other types of developers.” doesn’t belong there.. we’re talking pre-requisites, not personas.
One would expect instructions in such a page, not just a bulletpoint list of named techs. A bullet-point list of techs might belong to the Substreams overview in the first sections. The “Dependency Installation” already gives those instructions. So there’s nothing left for that page to exist. I suggest just moving the bullet-point list in “What is Substreams”, under a heading like “Substreams leverages powerful technologies”, and note something about these techs being mature, well documented and widely deployed.
Homepage
Arriving at the home page, I expect to find a clear, concise definition of what Substreams is. Perhaps swapping the first two sentences would do it. It’s more important to understand what it is, than who developed the technology.
The README.md https://github.com/streamingfast/substreams has a good 3-liner intro that we should use for the docs.
I’d also very much like to find here, right after Welcome, somethign exxttreeemly simple that can help bootstrap the mental model for Substreams. Something that includes a 3-lines mapper module, the presence of a Sink, a blockchain node. Something like the diagram in “Conceptual Diagram”.. It makes sense that it be up there.. so people can know where this whole thing fits.
We need at least the first paragraph of https://substreams.streamingfast.io/concept-and-fundamentals/definition on the first page.
Navigation
I’d love to have just two things under “Getting Started”:
The “Start Streaming” page has things that belong to a “Basics” section (which exists in the “Chain-agnostic Tutorial” (to become “Quick Start”).
I shrank the “Start Streaming” section, now it can become the first section in the Quick Start guide.. which makes sense. The fastest way to get started, is to just try it.. and then, write your very first thing.
Right now one needs to navigate and click a lot.. lots of pages, with similar sounding names: “Substreams” (first page), “What is Substreams” (hoped to find that on first page), “Conceptual Diagram” (and that’s not in What is Substreams?), “Fundamentals” (the first three pages didn’t cover the fundamentals?). Fundamentals could be named “How it works”, as it details some of the lower-level internals. People will want to get more into details in a “How it works” page.. and know what to expect. And we’ll know what to put there. That page can be longer, provided the headings are meaningful. For example “Key Steps” isn’t a meaningful navigation element. Same with “Working with Substreams Fundamentals” .. (working with the page? ooh.. sort of How to work with substreams fundamentals”).
Let's rename "Using the CLI” page -> “CLI Reference”