RGB Explainer

[BitcoinErrorLog]

Discuss incorporating a FAQ and/or Documentation area for RGB Website addressing explaining new entrants into RGB.

Examples (need to create full list and process for adding common Q's):

Devs Wtf is RGB, Spectrum? Why RGB instead of alternatives? How do I participate? What do I need?

Issuers How do I issue a token? How do I destroy tokens? How do I accept my token as payment?

Users How do I get RGB. tokens? How do I store RGB tokens?

etc

[UkolovaOlga]

I offer the following approach.

1. Add "How RGB works" as a separate section/tab to the RGB website in form of infographics of sort. Something similar to what NYT did about covid here

2. Create a repo called RGB FAQ in order to let the community ask questions about the protocol, use cases etc. by creating issues (potentially at some point enabling one part of the community to answer new questions with no core team involvement). This is the list of questions I have been covering thus far (will parse into issues in the FAQ repo):

• What does RGB stand for?
• What is LNP/BP?
• Why shitcoins? Why do we need them? Why RGB is important?
• How is RGB superior to the colored coins? + counterparty + omni/mastercoin + confidential assets
• Why not Ethereum?
• Why on the Bitcoin stack in general and why on LN in particular?
• What are singe-use seals?

• how do we reach agreement on the seals, specifically on the definition part?

• how do we construct the txn closing the seal?

• why/whether at all I change the state after defining but before closing the seal?

• how do I commit to the state while closing the seal?

• how do we define the next seal?

• how do we define and close the seal in LN? 
- how do we commit to a state in LN?

• how do we handle uncooperative closes in LN seals? 
- when closing the seal, should the next seal be defined in the output of the same txn? 
- can I use a UTXO with an advanced locking script with single use seals?
• Can I use a UTXO which is uneconomical to spend (‘dust’) to define and close the seal?
• How do I tweak a pubkey?
• What data is being committed to the pubkey tweak?
• Who knows about the data being committed?
• What is the difference between shared and owned state?
• Does owning the state relate to owning the asset?
• What is the difference between bitcoin script and simplicity in RGB?
• How can I route a multihop payment through LN and RGB?
• What is Spectrum?
• Do I need to close the seal with every transfer? Can I batch the seals into one transfer?
• How do we get the price for the RGB asset? *With and without Spectrum
• Are the Spectrum swaps atomic?
• Who needs to store the states data?
• What does the sender need to give to the receiver in order to transfer the asset?
• What are Confidential Assets/Transaction and how are they related to RGB?
• RGB/CA interoperability.
• Does an RGB txn leak any info to the base layer?
• Does RGB need CT on a base layer?
• How should I select a UTXO for committing a seal?
• What is the defining boundary for scalability of RGB?
• What is the size of txn proofs of the asset transfers?
• How can I prune the asset txn history?
• Can both the sender and receiver be offline during the txn process?
• Who are the trusted 3rd parties in RGB asset transfer?
• Is there any inflation risk?
• What type of asset can be issued using RGB?
• When I lose my offchain data will I lose my assets with it?

3. Create a RGB Knowledge base/Explainer website out of the FAQs, separating the information into pillars like @BitcoinErrorLog mentioned +adding other ones. I would not like to use the word "Documentation" as it can be misleading. Documentation is usually defined as a technical manual in order to implement something, but it's not the educational material, not the FAQ and not the use-case oriented content page. Imo, it's very important to distinguish between all those things at the level of bootstrapping the content/information sources of the project.

[MaxHillebrand]

If I may share some experience from the Wasabi documentation, although knowing that documenting/explaining a protocol and software implementation are very different, I think this is useful in general. The idea is to have different levels of depth and nuance in the explanation, from multiple pages, to a couple paragraphs, to a couple sentences.

We have three different sections:

Standalone Chapters

These are further separated in three pillars why wasabi [about the reasons for the importance of privacy and how the current status of it in Bitcoin], using wasabi [specifically on how to use Wasabi, this explains every function in detail, with step by step guides and rationals] and building wasabi [this is for existing and especially new contributors, with useful links and information].

Such a standalone chapter can go very much in depth, and explain the whole picture as is. If someone has general interest about the technology, this is the place to link them to.

For example in RGB, Single Use Seals could be a standalone chapter that covers it in depth.

FAQ

Here are frequently asked questions that come up in conversation with users, and they answer the question rather briefly and are limited in scope to the question. They also link to the standalone chapters for the user who wants more info. There is a lot of duplication between standalone chapters and FAQ, however, the FAQ should explain it shorter, and the FAQ can cover edge case topics that are not in the standalone chapter.

This is especially useful if the documentation has a search function. As the FAQ is also for users who have a specific question, and not just a general interest. So every time a user asks a specific question, this is the place to link them to.

@UkolovaOlga mentioned many great questions, and there are countless more that can be added. Though I think that some of them are very in depth already, and should be covered in detail in a standalone chapter, with an FAQ giving a tl;dr and linking to the chapter. For example, the What are singe-use seals?
 questions could give a two paragraph answer, linking to the pages long standalone chapter.

Glossary

This explains often used terms as briefly and condensed as possible, in one or two sentences. This is especially useful for new technology as RGB, because there are so many nuanced terms that are not widely known.

This is especially useful for a search function, as user who don't understand a word can get the gist of it there.

For example, Single Use Seals should have an entry explaining it in two sentences.

It would also be nice [not implemented in Wasabi unfortunately] if any word/term in a standalone chapter or FAQ can be hovered over to reveal the glossary entry, if it has one. Somewhat like wikipedia does it for cross-referenced articles.

[BitcoinErrorLog]

Alright, so we have a lot of good starting info here, should someone start a repo for fleshing out this FAQ, or where should we work? I like Max's outline advice too, maybe we can organize things similarly.