singnet / dev-portal Goto Github PK

We have a lot of markdown files that are actually raw html under docs/contribute/.

These should be converting to normal markdown so that we can maintain their content more easily.

This link
https://dev.singularitynet.io/tutorials/publish/docs/all/mpe/mpe-metadata.md

is broken in the file "https://dev.singularitynet.io/tutorials/publish/" in section 6, found in

This command will create service_metadata.json file. Please take a look into this file. You can find the >description of service metadata format in mpe-metadata.md

Main Source: https://dev.singularitynet.io/docs/concepts/

Suggested Structure:

1. Use component diagram across the whole video to explain them individually
https://dev.singularitynet.io/docs/concepts/#concepts-and-components
2. The SingularityNET Marketplace
 https://dev.singularitynet.io/docs/concepts/marketplace
3. Service 
https://dev.singularitynet.io/docs/concepts/service
4. The SingularityNET CLI
 https://dev.singularitynet.io/docs/concepts/snet-cli
5. The SingularityNET SDK 
https://dev.singularitynet.io/docs/concepts/sdk
6. The SingularityNET Daemon 
https://dev.singularitynet.io/docs/concepts/daemon
7. The AGI Token
 https://dev.singularitynet.io/docs/concepts/agi-token
8. The SingularityNET Registry 
https://dev.singularitynet.io/docs/concepts/registry
9. The Multi-Party Escrow Smart Contract 
https://dev.singularitynet.io/docs/concepts/multi-party-escrow
 https://dev.singularitynet.io/docs/concepts/mpe-stateless-client/
10. The Request for AI Portal (not on diagram nor documentation)

I followed the guide https://dev.singularitynet.io/tutorials/publish/

The docker images provides snetd-0.1.4, while snet cli is 0.1.9

So claiming funds fails with error "Payment type was not set by caller, return default payment handler defaultPaymentHandlerType=escrow"

Testing Environment:

Windows 10, Google Chrome 73.0.3683.86 (64bit), 15.6", 1920х1080

Proposition for improvement:

I think that detailed instruction for setup on Windows and MacOS are needed on that page
https://dev.singularitynet.io/docs/setup/requirements/
Also distributives for Python and Node.js are downloaded as easy to use installers but SNET CLI and SNET Daemon are downloaded as archives / folders. So it would be more convenient if their installation would be more intuitive too, like in case with Python and Node.js.

the idea here is to move the content which repeats across different personas in to one central place and replicate it through a scritp during deployement .
un referenced MD will also be deleted soon

On that page
https://dev.singularitynet.io/tutorials/publish/
we have such command
docker build -t snet_publish_service https://github.com/singnet/dev-portal.git#master:/tutorials/docker

As I understood from the discussion with developer it would be safer to replace it with such command
sudo docker build -t snet_publish_service https://github.com/singnet/dev-portal.git#master:/tutorials/docker

Because when I used the first command without sudo I wasn't able to build the container for sure

Put together code in tutorials/sdk.md, but that was before the PR was merged.

There should also be a warning on this page that the SDK is still in development and is liable to change.

Does the docker image require sign in to the Docker website itself? Or is the image file in some hidden location other than the folder I made for it?

Main Source: https://dev.singularitynet.io/tutorials/publish/

The first step in setup is "/docs/setup/create-a-wallet.md".

This is very basic at the moment, but would be a good place to introduce some Ethereum concepts or link to further reading about it. (what is a "wallet" vs "address", keeping your key secret etc)

I am not a native speaker so maybe I could misunderstand something here but according to the context "the above steps" in "If you are interested in using the Ropsten network for testing the platform with testnet tokens, please continue reading the above steps" should point to some info above that phrase while in the context of this page the info is actually below this statement.

The following tutorials contain incorrect commands to create the service metadata:
https://dev.singularitynet.io/tutorials/publish
https://dev.singularitynet.io/tutorials/process

Tutorial commands fail because payment address is not a part of a service metadata anymore. Tutorials don't contain information about organization metadata.

On that page
https://dev.singularitynet.io/docs/setup/call-a-service/
we can such command for installing SNET CLI
pip install snet-cli

But on that page
https://dev.singularitynet.io/docs/setup/requirements/
there is another command for the same operation
sudo pip3 install snet-cli

As I understand
sudo pip3 install snet-cli
is the right one

In any case it's better to keep to approach of consistency when we have same commands for specific operations / same links to the specific resources and so on (on different pages of Dev Portal)

Trying to manage the prev/next links is error prone. Inserting a new page requires change 4 values (one in the pages either side, and two in the new page).

The Jekyll documentation has a better way, using a _data file that describes the desired order

The include that renders the prev/next links is https://github.com/jekyll/jekyll/blob/master/docs/_includes/section_nav_tutorials.html

I can see the link to
https://docs.docker.com/get-started/
on that page
https://dev.singularitynet.io/tutorials/publish/

Just that maybe it can be good to mention several simple commands for basic Docker installation on this page of Dev Portal?
To give developers a possibility to not dive too deep into it but just install the Docker and proceed further

Though the link "Get Started Guide" to the Docker can be left to provide quick access to detailed information if it will be interesting for specific developer

how-to publish service (https://dev.singularitynet.io/tutorials/publish/) uses outdated treasurer logic.
In the current version you should use snet-cli to claim funds (see front-to-back example)

I don't think we need to keep this very early documentation around, and if we need it it'll be in the repo history.

We have some pages that unnecessarily use directories, making it annoying to edit content. In editor tabs it shows up as lots of index.md files opened.

People should use directories only if needed. e.g. there is associated content (some of the tutorials) or there is a nested structure to the content itself.

Even for associated content, I think it'd be better to keep our documentation separate from the actual scripts and code.

These guidelines should be added to #37 if agreed upon.

Main Source: https://dev.singularitynet.io/docs/setup/

1. Installing dependencies using Docker 
https://hub.docker.com/r/singularitynet/snet-platform
2. Installing dependencies using the CLI
 https://dev.singularitynet.io/docs/setup/requirements/
3. Creating a wallet with Metamask 
https://dev.singularitynet.io/docs/setup/create-a-wallet/


This page discusses how to insert a edit link to github source.

The code to add to our layouts is:
<a href="{{ site.github.repository_url }}/tree/master/{{ page.path }}">Edit</a>

I feel like this should be at the top of the page so it's visible, but out of the way. Maybe just a pen icon below the contents that get displayed on the right-hand side?

I am not a native speaker but I have such thoughts: maybe it's good to

1. Replace this
   The SingularityNET Marketplace provides an easy way for people browse available AI services and interact with them via a web interface.
   with that
   The SingularityNET Marketplace provides an easy way for people to browse available AI services and interact with them via a web interface.

2. Remove "and" in the end of this point
   "allows consumers to rate services they have used; this is a simple rating component that will eventually be replaced by SingularityNET’s Reputation System (currently under development); and"

3. Write Ethereum from capital letter here
   "The Marketplace is a DApp, which means in order to use it you need to install a ethereum browser extension like MetaMask."

4. Replace this
   In the context of the marketplace it lets you query what services are available, transfer AGI funds into escrow, and setup payment channels that allow you call any of the listed services.
   with that
   In the context of the marketplace it lets you query what services are available, transfer AGI funds into escrow, and setup payment channels that allow you to call any of the listed services.

5. I am not sure if this phrase will be completely clear for everyone (mainly about certbot and letsencrypt). Maybe it would be much more evident for the developers but still.
   Ensure you are using SSL with the snet-daemon. We recommend using certbot and letsencrypt if you don’t already have a SSL certificate.

We have a lot of duplicated files and content which makes the dev portal a pain to maintain.

e.g docs/all/mpe/front-to-back-examples/scripts/example1/example.md vs docs/all/mpe/front-to-back-examples/scripts/example1/index.md

There's also a lot of other content that's been copy-pasted around the place for no particular reason. Please stop and consider why you are copy and pasting content. If it belongs in a new place, then consider deleting where it came from or writing it to be specific to the current article.

Testing Environment:

Windows 10, Google Chrome 73.0.3683.86 (64bit), 15.6", 1920х1080

Precondition:
User has 2 AGI on Escrow Balance

Steps to reproduce:

1. Navigate to https://dev.singularitynet.io/docs/setup/requirements/
2. Try to execute all commands from the instruction in the terminal on Linux
3. Observe the result

EXPECTED RESULT:

All commands are executed properly after copy-paste to the terminal

ACTUAL RESULT:

The last command "export USER_ID = $USER" isn't executed properly because it has excessive spaces around "=" while all other commands don't have it

• Only show three cards for "Core Concepts", "Setup Guide", and "Tutorials"
• Remove "All Docs" and "View on Github" buttons
• Reduce white space in header at home page so that three cards are visible on laptop sized screen.

https://help.github.com/en/articles/creating-a-custom-404-page-for-your-github-pages-site

Main Source: https://dev.singularitynet.io/docs/concepts/marketplace/

Video Tutorial from Beta Launch: https://www.youtube.com/watch?v=j_9yLRQ1bE4
Please let me know if you think this video does not contain enough information to be the tutorial of the DApp, and in that case what needs to be added.

Main Source: https://dev.singularitynet.io/tutorials/integration/

Suggested Structure:

1. Supported Languages
https://dev.singularitynet.io/tutorials/integration/#-supported-languages
2. Supported Frameworks
https://dev.singularitynet.io/tutorials/integration/#-ai-frameworks
3. Service Metadata
https://dev.singularitynet.io/docs/concepts/service-metadata
4. Service Naming Standards
https://dev.singularitynet.io/docs/concepts/naming-standards
5. Service Documentation
https://dev.singularitynet.io/tutorials/integration/#-service-documentation
6. Third-party code and models
https://dev.singularitynet.io/tutorials/integration/#-third-party-code-and-models
7. Marketplace Requirements
https://dev.singularitynet.io/docs/concepts/marketplace/#marketplace-requirements

In singnet/snet-daemon#202 daemon_endpoint has changed to daemon_end_point. Documentation needs to be updated to reflect this prior to release of a new daemon version.

These are how to use the dapp (step 3) and snet-cli (step 5) to call a particular service.

• the dapp needs a video and/or screenshots.
• snet-cli needs to show the command and output verbatim.

We should use the same service (snet/example-service) for each.

1. You can see "Edit" button on this page for example
   https://dev.singularitynet.io/docs/setup/

I suppose that this button is present here just for the convenience of developers, like to have a possibility to quickly switch to the source of the page. If it's correct then ofc I think that it would be better to finish some related works soon and to remove this button. Because as I understand it's not necessary for the users and the portal should be perceived as some finished product in my view. Although it's totally ok to update the info iteratively and to extend it later.

2. I can see some "TODO" blocks, for example, on that page https://dev.singularitynet.io/docs/setup/call-a-service/
   I guess it's the similar issue as with "Edit" button
   So these blocks indicate for the developers that something is "to be completed" later
   But as I remember the developer portal is live for 6 months so I suppose that it's good to keep the pages without such blocks or make it a bit more accurate somehow
   Otherwise it produces an impression of some draft while the website is actually live and it's open to the public

3. On that page
   https://dev.singularitynet.io/tutorials/sdk/
   I can see such command with additional phrase
   pip install snet-sdk (check this is correct)
   So I guess it's the same situation here, it would be nice if such questions can be clarified and removed as soon as possible

I can't get to the sign up page on this link: https://beta.singularitynet.io

However I can get to the sign ups following this link: https://beta.singularitynet.io/signup Is this something others have experienced?

On the page
https://dev.singularitynet.io/docs/setup/create-a-wallet/
we have such phrase
"Users are required to visit a Ropsten Faucet, which is a per-request Ropsten Ethereum distribution hub."
Ropsten Faucet is a link here which leads to https://faucet.metamask.io/
While on the page
https://dev.singularitynet.io/docs/setup/call-a-service/
we have such phrase
"Luckily for test networks you can go to a faucet to request some Ether for free."
Here "go to a faucet to request some Ether for free" is a link to https://faucet.metamask.io/
So I suppose that it can be good to make this link consistent throughout the whole website
I mean to provide the link to the same Ropsten ETH on all pages where it's necessary or provide two links together on all these pages to give users a choice between these faucets.

We want to centralise our documentation in the dev-portal.

Doesn't apply to AI research and AI services.

Any relevant wikis should have their content moved and be archived/deleted.

'docs/marketplace.md'

Since we are still confirming these, we should update the marketplace requirements page when we know more.

It is just extra noise to list the dev-portal repo structure for someone who is just trying to get started with SingularityNET.

Maybe "Repository Structure" is useful for someone who wants to contribute to the documentation, but not in the "Getting Started page" that should optimise for getting people working with the platform as fast as possible.

The high-level "Planning" section is also of almost no utility to someone just trying to use SingularityNET. It should be moved to an "About" page if needs to be on the dev portal at all.

This page has a bunch of stuff that doesn't apply to external developers:

https://dev.singularitynet.io/docs/all/service-integration-guidelines/#third-party-code-and-models

specifically: stuff about cost, attribution, and what files are mandatory are not up to us to decide.

This issue is to share developer portals and documentation sites that we think are particular nice looking and/or functional.

Clicking "All docs" from top right of https://dev.singularitynet.io/docs/all/getting-started/ - sends one to https://dev.singularitynet.io/docs/ - which then requires clicking on "View all docs".

Main Sources: https://dev.singularitynet.io/docs/concepts/snet-cli/
http://snet-cli-docs.singularitynet.io/
https://dev.singularitynet.io/docs/setup/call-a-service/

Use the example of how to call a service to introduce users to the CLI and connect them to relevant documentation.

Ask people to:

• use consistent tabs vs spaces
• don't insert BOM headers into files which prevents Jekyll compiling them.
• use markdown over raw html (#32)
• don't create directories with only an index.md (#38)

The link in the footer is "Company Main Site", which is confusing when we've been registered as a foundation.

I disabled all comments in 9efeb87

This is because the comment iframe shows up with an "Error embedding" message, and complains about the discourse forum having the wrong origin policy.

I think there was a question about whether we still wanted comments on every page, but if we do then someone will need to investigate what is causing the error.