Light-client: Restructure SDK docs

[taleldayekh]

Description

If we are to follow the __simple, clear and short__ approach when writing docs we need to start by going through the SDK docs and make sure it complies to those requirements.

Currently (link to docs) all information is clustered together in the "Getting Started" section whilst a list of classes, enums and interfaces are gathered in a long menu that dominates the left side of the page.

As a reader I'm drawn to the list on the left and if I'm completely new to the SDK that gives me little to no information on how to go about implementing it. Even though things are well documented, information risks getting lost if it is not presented in a hirarchy a reader expects.

New structure

• Add a separate introductory page
• Add a separate page outlining prerequisits and requirements
  
  
  
  • i.e. Node.js, basic Web3 knowledge and some references on how to set up a Raiden node
  
  
• Break down the "Getting Started" section into smaller actionable steps that introduces key concepts in a logical order
  
  
  
  • This can be done in several ways. One alternative is to walk the reader through building a simple demo app and in the process introduce all key concepts and functionalities of the SDK
  
  
• Add a separate page for classes, methods and enums
  
  
  
  • These are more relevant as references when you're already somewhat familiar with the SDK. They should be easily accessible for anyone needing to look them up but not necessarily the very first thing you click on when starting to explore the SDK
  
  
• Remove all references to SDK docs outside the current docs
  
  
  
  • This goes hand in hand with having everything accessible in one place instead of spreading our resources across several places. If we are referencing SDK related information in other places, i.e. GitHub readmes, it might be a good idea to bring that information in to the SDK docs and remove the reference.
  
  

Next steps

• [x] I will await additional feedback, after that each of the bullet points from above can be made into separate issues and tackled accordingly.

Acceptance criteria

• The documentation of the SDK is restructered
• Keeping the writing there (nothing to add)
• All the new content is shown in https://lightclient.raiden.network/docs/

cc @christianbrb

273

[christianbrb]

@taleldayekh Nice 👍

We also have got the Wiki . How do we include this?

[taleldayekh]

As I understand it the wiki is mainly for anyone interested in contributing to the code base? Maybe it should stay in the GitHub repo and we can reference it in the readme.

In the docs we need to include a link to the GitHub repo anyways. Anyone who is interested in the codebase will find all relevant information for working on the code by looking in the repo.

[nephix]

The docs (https://lightclient.raiden.network/docs) are generated from the repo during the build process, so anything in the repo could potentially also be included into the docs easily (e.g. the contribution guide)

[taleldayekh]

Does something like this makes sense as a first restructuring of the docs? @andrevmatos @nephix @kelsos @christianbrb

# Home (sidebar header)
      |-- Home (page)
          * Short about the Raiden project (one sentence)
          * Short about the SDK
          * "Get Started"-link
          * Display npm install raiden-ts command
# Get Started (sidebar header)
      |-- Installing and importing raiden-ts (page)
      |-- Connecting to a Raiden test network (page)
      |-- Using the SDK in a private chain or a dev environment (page)
# Usage (sidebar header)
      |-- Opening a channel (page)
      |-- Funding a channel (page)
      |-- Transferring via a channel (page)
      |-- Closing a channel (page)
      |-- Settling a channel (page)
# API (sidebar header)
      |-- Classes (page)
      |-- Enums (page)
      |-- Interfaces (page)

[nephix]

Looks good to me, just two things maybe:

• Will requirements / pre-requisites go under Installing and importing raiden-ts?
• Transferring via a channel might make sense to name this something like Direct Transfer so we can later on add pages on how to do mediated transfers etc

[taleldayekh]

I'm thinking of having that as its own section just before "Get Started". And regardign your second point I agree, we should call it direct transfers.

[christianbrb]

@taleldayekh Looks awesome :)

Some small things:

• Shouldn't we remove most of https://github.com/raiden-network/light-client/blob/master/raiden-ts/README.md
• Shouldn't we remove most of the section https://github.com/raiden-network/light-client#start-developing and link to the docs

[taleldayekh]

Yes, you're right, we should clean up the SDK README.