Improvements to the documentation and Quickstart flows

[jamiehewitt15]

Prerequisites section

We should add a list of prerequisites e.g. node.js, a Unix based operating system (Mac or Linux) etc

Quickstart Section

• I suggest we add explanations YOUR_INFURA_PROJECT_ID, metadataCacheUri, and providerUri
• We should make sure that we provide all the terminal commands that are required to get setup initially.

Simple flow

It would be good to provide code examples that work as-is so that the user can just copy and paste them to get started, without having to edit them. This helps make the quick start even quicker and is very useful for beginners who are not familiar with the tech.

We should also add the terminal commands that are required for making new files, installing dependencies, compiling typescript, and running the files.

There are various issues with the code snippets that we should improve to make it easier for beginners:

Snippet 1:

• await is not inside an async function
• ocean is not defined
• DataTokens is not defined
• contracts is not defined
• factoryABI is not defined
• datatokensABI is not defined
• web3 is not defined

Snippet 2:

Each of the environmental variables should be explained so that the user knows what values to enter where to get them from.

Snippet 4:

• await is outside an async function

Snippet 5:

• getInstance() expects 1 argument but there are 0
• .download() Expected 5 arguments, but got 4.

Marketplace flow:

Snippet 1:

• await is outside an async function
• LogLevel is not defined

Snippet 2:

• service1 is not defined

Snippet 3:

• tokenAddress is not defined

Snippet 4:

• await is outside an async function

Snippet 5:

• price is not defined
• assert has not been imported

[trentmc]

I like these suggestions and agree with them.

In the last several weeks, we've made many improvements to ocean.py quickstarts etc that reflect some of the goals above. Therefore ocean.py might be useful as a pattern for ocean.js.

[jamiehewitt15]

Thanks, I've opened a draft pull request for this #669

I had a look at the ocean.py documentation and it does seem better. The "Learn More" section is a good idea, I'll add that here. The quickstart flows are also a lot more clearly explained. I notice that the ocean.py simple flow uses barge which is not used in the the ocean.js simple flow.

[trentmc]

:)

ocean.py used to use rinkeby, not barge, but we recently moved it over to barge because it's simpler / faster to get going. Then the "learn more" part talks about how to link to services in more detail.

[trentmc]

@jamiehewitt15 I believe you're working on this? If yes, please assign the issue to yourself, and move it to the "in progress" kanban column. Thank you!