dfuse-io / docs Goto Github PK

Currently, we have 8 page params on most pages that need to be managed manually.

• weight: used to define page rank in a list of pages in the same folder
• pageTitle: used to define the title of the page
• pageTitleIcon: used to define the icon next to the title of the page
• sideNav: used to show or hide the left side nav
• sideNavTitle: used to define the title shown on the left side nav if the left side nav is visible
• sideNavLinkRename: used to rename the side nav link of the current page
• BookToC: used to show or hide the right side nav (table of content)
• release: used to display a stable, beta, alpha status tag next to the page title

A bunch of these could be automated (or defaulted) just by looking at the section (url) and returning a default value based on that.

pageTitleIcon could be defined by the url https://docs.dfuse.io/eosio https://docs.dfuse.io/ethereum https://docs.dfuse.io/platform e.g. pageTitleIcon: eth if the root folder in the url is ethereum.

sideNav could be true only if we're not at the root of a section. e.g. sideNav: false if the url is anything else (if we're deeper) than https://docs.dfuse.io/eosio or https://docs.dfuse.io/ethereum or https://docs.dfuse.io/platform

sideNavTitle could use the section's sub-section to define itself. e.g. sideNavTitle: dfuse Cloud if the url is https://docs.dfuse.io/platform/dfuse-cloud or https://docs.dfuse.io/platform/dfuse-cloud/xxxx

Python and Go guides use gRPC, which depends on the protobuf files. Currently, the examples reference public repos that contain a copy of the protobuf files that may or may not be out of date.

A solution would be to create a public repo that would become the source of truth for protobuf files.

Furthermore, a user going through the guides right now need to have protoc installed and compile the protobufs themselves. Ideally, we should provide compiled protobufs in this repo as well, so that we can simplify the guides. The user would simply wget the compiled files, and carry on with the rest of the tutorials.

cc @billettc

In order to improve on-boarding experience, graphiql should have a button that generates a Golang / Python, etc code snippet matching the playground.

The examples to be ran on graphiql are missing a required argument indexName for searchTransactions.

https://github.com/dfuse-io/docs/blob/2918f4471770add56ce7c12655ab1e0e54eb550b/content/guides/core-concepts/graphql.md#subscriptions

https://github.com/dfuse-io/docs/blob/2918f4471770add56ce7c12655ab1e0e54eb550b/content/guides/core-concepts/graphql.md#paginated-queries

https://github.com/dfuse-io/docs/blob/2918f4471770add56ce7c12655ab1e0e54eb550b/content/guides/core-concepts/graphql.md#navigating-forks

We're currently displaying all available sections in the left side nav, but all sections except the current one should be hidden to the user to remove as much noise as possible from the screen. The top level nav is used to navigate the sections, the left side nav is used to navigate the current section only, and the right side nav is only used as a table of content for the current page.

The side nav title is also redundant and the second one should be removed.

The pricing banner takes up too much real estate in the docs. It should auto-collapse after x seconds or give the user the option to close the banner. It's bad UX in general to leave a notification banner with no way to close it by the user. Especially if the banner pushes all the content down instead of overlapping current content.

https://docs.dfuse.io/eosio/public-apis/samples/
https://docs.dfuse.io/ethereum/public-apis/samples/

The the old staging environment (https://staging.docs.dfuse.io/) is

1. Being indexed by Google - no staging environment should be indexed by search engines.
2. Online -- it’s not needed anymore and should be taken down.

If, for some reason we still need this staging environment, please add this meta to all pages:
<meta name="robots" content="noindex">

This will stop crawlers from indexing the staging environment. If we can shut it down, let’s just take the server down.

Transferring over the issues that were opened on the old repo.
https://github.com/eoscanada/dfuse-documentation/issues/8

https://docs.dfuse.io/guides/core-concepts/cursors/#graphql-query-pagination
Example says to use the second result's cursor, but references the wrong txHash

Has the REST API service been suspended?

suddenly use api, i get a 404 status response

All links sending users to https://app.dfuse.io to create a free account should be edited to https://www.dfuse.io/pricing instead of https://app.dfuse.io because of the recent pricing changes. It will allow users to select a free account for testnets (dfuse) or the Community Edition (EOS Nation).

Subsequently, we could have 2 buttons, one with a link to the free testnet account, and one to the CE account, but it will become hard to maintain at some point. I believe that the first approach is best.

The service name in the Go example should be dfuse.graphql.v1.GraphQL instead of dfuse.eosio.v1.GraphQL

See this line and that line.

Migrating issues from the old repo, see eoscanada/dfuse-documentation#15

Some endpoints are still considered alpha or beta in the docs. Some are stable, but might be in alpha or beta. That should be revised to make sure the docs are aligned with the current status of our APIs.

GET /v0/search/transactions [  GitHub  | [ www ](https://docs.dfuse.io /eosio/public-apis/reference/rest/get-search-transactions/) ]

If I try to call this endpoint I receive http status 410.
Am I doing sth wrong or this is going to be removed? Please update documentation properly :)

Migrating issues from the old repo, see https://github.com/eoscanada/dfuse-documentation/issues/1

https://docs.dfuse.io/eosio/public-apis/release-notes/
https://docs.dfuse.io/eosio/admin-guide/release-notes/

and eventually https://docs.dfuse.io/ethereum/public-apis/release-notes/
https://docs.dfuse.io/ethereum/admin-guide/release-notes/

These should be automatically fetched when we have a new release (or update an already released "release notes" with new notes or corrections). https://github.com/dfuse-io/dfuse-eosio/releases is our single source of truth.

For the Public APIs release notes, everything between # Public API Changes and # System Administration Changes should be included in the release.

For the [System Admin] release notes, everything after # System Administration Changes should be fetched.

We'd like to have markers inside .py, .go, .js example files. Currently, they are in quickstarts/*.

Example:

func main() {
    var prep = "hello"
// DFUSE:BEGIN:quickstart_go_search_eos_section1
    var some = "code"
    var to = "show"
// DFUSE:END:quickstart_go_search_eos_section1
}

We need a preprocessing step, that will crawl all files under quickstarts that contain those DFUSE:BEGIN tags. We ignore the first chars (no matter how they're commented out.., with #, or ;; or // ...)

We build a .json output that we drop in /data/samples.json, looking like:

{"quickstart_go_search_eos_section1": "    var some = \"code\"\n    var to = \"show\""}

In hugo, we can reference these with {{ .Data.samples.quickstart_go_search_eos_section1 | highlight }}

Replace those line numbered samples that extract from the quickstarts right now, with this new method.

• Implement Ethereum versions of samples when available

• Migrate public github example repos to docs repo

• example-graphql-grpc

• example-search-ethereum

• example-stream-ethereum

• example-stream-transfers (eos)

• example-dfuse-events

• example-stream-action-rates (eos)

• example-transaction-lifecycle (eth)

• example-graphql-apollo

• example-graphql-apollo-stats

• example-graphql-python

• example-eos-rex-price-feed

• example-push-notifications

• example-dfuse-events-contract

• example-node-server

• example-eosjs-decode-hex

• example-push-guaranteed

• Migrate advanced examples from client.js to docs

To Review: https://github.com/dfuse-io/client-js/tree/master/examples/advanced

How should I close the stream in "for rawResult in stream"

Migrating issues from the old repo. See https://github.com/eoscanada/dfuse-documentation/issues/9

If a user is logged in, the dfuse docs should be displaying examples with the user's token, like Stripe is doing, so that the examples can be copy and pasted as is.

e.g. when you go to https://docs.dfuse.io/ethereum/public-apis/getting-started/ you're basically looking at https://docs.dfuse.io/ethereum/public-apis/getting-started.md

The content of that page was manually created Text + links to sections) but it could be auto generated so that when we add a new page or sub-section, a link will appear on _index.md page.

It is currently hard to know in which section you are (EOSIO, Ethereum, Platform) from a quick look at your screen. For a better UX, I believe the bg color of the top banner should be different, depending on the section that you're currently in.

e.g. using the brand color as the bg color of the section's top banner
EOSIO: #111A44
Ethereum: #8B93B3
dfuse Platform: #FF4660

@avionrouge feel free to make suggestions to enhance the UX as well.

Check #93 with someone from engineering team to make sure the temporary descriptions taken from the component READMEs are accurate.

Using [Reference: Ethereum Search Terms](/ethereum/public-apis/reference/search-terms) vs using
[Reference: Ethereum Search Terms]({{< ref "/ethereum/public-apis/reference/search/search-terms" >}})

if we don't use ref, then build-time link checking isn't done
e.g. when someone renames a file, it'll go unnoticed

In the "Initiating dfuse Graphql Server connection" section found here: https://github.com/dfuse-io/docs/blob/master/content/guides/eosio/tutorials/push-notifications.md
It says that endpoints can be found on the endpoints page. However, the listed endpoints don't include a port, but this one does. Should be consistent (but I'm not sure which it should be always)

This will enable searching in docs, otherwise user needs to navigate heuristically.

To better reflect our new website structure, each "core feature" should have a dedicated section in the docs with examples to better expand on what these features are, use cases and examples on how to use them.

e.g. State
Lifecycle
Search
Push Guarantee

The website will have 1 page per feature, explaining the feature and linking to the docs where that feature is explained in more technical details.

A first pass has been done to re-direct the old docs structure to the new one, but there were some recent changes that might have broken that already. A better job needs to be done to compare the old docs url to the current one and create aliases on each page as required.

https://docs.dfuse.io/eosio/public-apis/reference/rest/get-state-table-row/#abi-handling

Missing a word in this sentence: The dfuse API tracks ABI changes and will something the row with the ABI in effect at the block_num requested.

Migrating issues from the old repo, see https://github.com/eoscanada/dfuse-documentation/issues/19

I wasn't sure how to properly remove this, as it is pulling the code snippet from somewhere else, and I'm not sure how it should/needs to be changed.

On this page: https://docs.dfuse.io/guides/eosio/getting-started/other-languages/
under number 6 - Full Working Examples, the code snippet in Go just below there contains

    case "ethereum", "ETH":
        streamEthereum(context.Background())
    default:
        streamEOSIO(context.Background())```

But maybe it needs to contain that as it does something different for each chain.