raiden-network
Improving readability of SDK-Development docs
User Story
As Chris I would like to read the SDK-Development docs with as little friction as possible. The SDK-Development docs is an in-depth account of the architecture and technical workings of the SDK. This, however, should not prevent us from writing it in a more easily digestible way without for that sake leaving anything out.
Acceptance criteria
I'll provide two before/after examples of what I consider as a more digestible text. Perhaps they can be used as references for the acceptance criteria.
Before
Raiden client class is the entrypoint for the public API. This class's focus must be Developer Experience (DX), so we should avoid exposing too much of the internals on it, as well as providing anything needed for every reasonable usecase. This balance is important to be kept in mind, and is team's responsibility to decide on whatever non-trivial decision. It's desirable for the interface's changes to be as backwards-compatible as possible, although this isn't guaranteed before MVP release.
After
The Raiden client class is the entrypoint for the public API. The focus of this class is Developer Experience and we should avoid exposing to much of its internals while still providing what is needed for every reasonable use case.
This balance is important to keep in mind. It is desirable that changes in the interface are as backwards compatible as possible, although not necessarily before a MVP release.
Before
One of the main development targets is correctness and TypeScript compile-time checks to aid implementation, validation and integration of the diffent parts of the codebase. io-ts is a library which all allows to bridge the gap between TypeScript's compile-time safety and runtime validations. Basically, the problem it solves is: you can tell TypeScript that a function argument, return or a variable is of a given type, and it'll help you not do wrong things with this information (e.g. passing a number to a function which expects a string) while writting your code; but when you're dealing with unknown data (e.g. a handled state file, a incoming message, etc), you can't be sure it matches your expectations, and if not, very bad things can happen.
After
TypeScript helps us check for correctness and aid implementation, validation and integration of various parts of the codebase. We can tell TypeScript what type of argument, return value or variable is expected in a function which helps us avoid passing wrong types when writing our code, like passing a number to a function that expects a string.
However, when we are dealing with unknown data we cannot always be sure it matches our expectations. To bridge this gap we use the io-ts library.
Tasks
- [ ]
Test with the premium version of Grammerly to speed up the process.
Result
Not as good as expected. Some minor issues have been corrected, but not the overall structure (e.g., long sentences). Maybe it is good enough.
Before
Raiden client class is the entrypoint for the public API. This class's focus must be Developer Experience (DX), so we should avoid exposing too much of the internals on it, as well as providing anything needed for every reasonable usecase. This balance is important to be kept in mind, and is team's responsibility to decide on whatever non-trivial decision. It's desirable for the interface's changes to be as backwards-compatible as possible, although this isn't guaranteed before MVP release.
After
Raiden client class is the entry point for the public API. This class's focus must be Developer Experience (DX), so we should avoid exposing too much of the internals on it and providing anything needed for every reasonable use case. This balance is vital to be kept in mind and is the team's responsibility to decide on whatever non-trivial decision. The interface's changes should be as backward-compatible as possible. We don't guarantee this before the MVP release.
Before
One of the main development targets is correctness and TypeScript compile-time checks to aid implementation, validation and integration of the diffent parts of the codebase. io-ts is a library which all allows to bridge the gap between TypeScript's compile-time safety and runtime validations. Basically, the problem it solves is: you can tell TypeScript that a function argument, return or a variable is of a given type, and it'll help you not do wrong things with this information (e.g. passing a number to a function which expects a string) while writting your code; but when you're dealing with unknown data (e.g. a handled state file, a incoming message, etc), you can't be sure it matches your expectations, and if not, very bad things can happen
After
One of the main development targets is correctness and TypeScript compile-time checks to aid implementation, validation, and integration of the different parts of the codebase. io-ts is a library that allows bridging the gap between TypeScript's compile-time safety and runtime validations. The problem it solves is: you can tell TypeScript that a function argument, return or a variable is of a given type, and it'll help you not do wrong things with this information (e.g., passing a number to a function which expects a string) while writing your code; but when you're dealing with unknown data (e.g., a handled state file, an incoming message), you can't be sure it matches your expectations, and if not, nasty things can happen.
