Victor felt that I should share my thinking:
High-level design document
This is document serves the purpose of advocacy.
It goes from the use of blockchain (frictionless market / limitless integration) to the method to achieve it (tokenisation) to the features we desire from it to the architect thinking on how to satisfy these features.
There is no need to mention any source code or functions, and any reader who did architect thinking on the blockchain before and understands well the current web 2.0 module should be able to read it.
I wonder how much of web3 should be in it, because despite Tokenisation being a key aspect of web3, it is not the entirety of it, yet most web3 supporters haven't seen how tokenisation plays a key role in it. Focusing on web3 might bring them in.
This document needs to be pruned and grown once a year or half a year.
Guides
This is a set of articles/documents for developers, organised by goals or topics. This is the core part of our document. They are published on TokenScript.org website.
Each guide has both:
𝑎) Mid-level architect concepts
The goal is to explain concepts and technologies and connect them to business cases.
The goal of this one is:
- Serve as an introduction to prepare readers to read the tech spec.
- Help implementors to orient their effort.
- Serve as the reference points from guides.
This is developed with a bit forward-looking attitude than the following two documents.
𝑏) Tutorials
This has the step-by-step instruction on how to get something running. There are a few good examples of how this is done:
- Spring Boot is Bældung's serial of guides. It's concise, with actual code and didn't try to overwhelm a reader with explanations. The disadvantage (arguably) is that by not explaining the code much, these guides serve as reference better than learning material.
- AWS tutorials. Again they are concise and arranged with the questions the readers might have in their mind, and uses real business scenarios.
If there are any developer tools, this is the place they are taught. As well as debug methods.
Why 𝑎+𝑏 in the same place
- Help a developer learn by examples and by concepts at the same time.
- Not only providing code but the context, for a developer to understand when/why use a tech.
- Providing both visionary (mid-level architect concepts) and runnable (tutorials) in the same document so that the tutorials serve to explain the vision on a lower level
RFC-style specs
This has the technical detail that is summarised from the TokenScript weekly meetings. It's mainly for TokenScript Engine implementors but is a very useful reference to the developers. This is where answers to StackOverflow questions often link to. The Ethereum yellow-paper is a good example of this document.
Of course, this one only covers the spec-out techs.
Search-key matching TokenScript blogs
- Once in a while, there are media keywords that are relevant to TokenScript. This is about blogs that connect one thing people are familiar with to a feature in TokenScript.
- Sometimes people would search for a frequently asked question about TokenScript. Have a blog post to catch these search queries.
| Type of Doc | Reader | Location | Update frequency |
|---|---|---|---|
| HIgh-level design document | Blockchain and web3 thinker/dreamers | TokenScript github | yearly |
| Guides | Developers, archtects, ethusiastics | from a new Guide repo on github, published to TokenScript.org | as TS engines release |
| RFC-style specs | Developers, Engine implementors | TokenScript github | as each topic in TS Weekly matures |
| blogs | everyone | TokenScript.org and/or aw.com | as new keywords discovered |