Payments Chapter Structure: Unified way to communicate both on-chain and lightning #98
Replies: 2 comments 4 replies
-
|
Awesome, thanks Johns. I too had a whole bunch of 'basics / foundations' in the beginning of the private key chapter when I started writing. I would suggest shaping the structure so that it starts with the basic user need (sending or receiving transactions) and then digging deeper and referring to terms as it is needed. I would also suggest to focus primarily on on-chain transactions (although I would not call it that, just payments or transactions) and leave Lightning/off-chain to after the reader has grasped the basics there. |
Beta Was this translation helpful? Give feedback.
-
|
I think starting with simpler stuff and expanding them gradually makes sense. Glossary will always be there to move important terms that overlap within different parts of the guide as Daniel mentioned. It all comes down to, who is our target audience and how much technical and in-depth information they really need to be able to understand certain concept so that they can design a Bitcoin application. I commented earlier on the structure, and to me it makes sense, but we need to see which of these sections are more suitable for other parts of the guide. @johnsBeharry My recommendation is that now that you have a big picture on structure begin with smaller chunks and most basic concepts. Once those are in the guide, we'll get a better feeling on how to expand them. In my view:
Are sections that definitely can be good basis on which we can build on. And all of these PR's are great, even if we fit them in glossary or even separate sections, it's still good. Privacy for example can probably be a whole new section just like Private Key Management. |
Beta Was this translation helpful? Give feedback.
-
|
Thanks for this input @danielnordh @pavlenex. Agreed I think it makes sense to have for example Privacy & Security under its own section, and even Account Scanning & Discovery could be under Recovery / Migration. I think we should look at the entire user flow of a bitcoin application then fit the content we come up with in the guide into that. That would also be a structure that would allow us to communicate both lightning and on-chain unified way with two Send and Receive chapters. As for a page like Units & Symbols and Wallet Interoperability that is being written in PR #30 they can be in a Foundations page (Wallet Interoperability is currently looking for a section). Thoughts? |
Beta Was this translation helpful? Give feedback.
-
|
I just created a new "Foundations" section in #108 . That structure makes sense to me. Only thing we need to be clear about is the difference between "Getting started" and "Foundations". "Getting started" is more top-level and even interesting to understand Bitcoin design and user experiences as a non-designer. "Foundations" is about practical design basics and more helpful when you're actually working on something. That's how I look at it at least. What do you think? |
Beta Was this translation helpful? Give feedback.
-
Agreed with this. Perhaps we state clearly the criteria for what gets into both. Hopefully it doesn't become like the "lib" folder in development which turns into a dump for uncategorised source code. |
Beta Was this translation helpful? Give feedback.
-
|
I had a hard time visualizing the flow of this chapter so made an attempt at reorganizing the structure you outlined above @johnsBeharry as if I had tackled it in my own way. I do not want to step on any toes here, please see this as an attempt to help. Basically all the same information you have outlined should fit in here, I have just attempted to streamline it from a readers point of view. It might be easier to comment in a doc so here's a link: https://docs.google.com/document/d/1Dhu2StMmHEDVTSNdlkQ7Asl695Z97c5qt7j1adjxV3s/edit?usp=sharing [Page] - Payments introduction(give an overview of the chapter with links to individual pages, similar to https://bitcoin.design/guide/getting-started/introduction/)
[Page] - Transactions overviewIntroduce basic transaction concepts and the lifecycle.
Link to glossary, foundations etc for things terms that need longer explanation (Units & symbols, address types etc.) [Page] - Sending bitcoinExplain what goes into sending bitcoin.
Link to advanced information on separate page (like coin selection, coin join, labels etc.). [Page] - Receiving bitcoinExplain how receiving/requesting bitcoin works.
Link to advanced information on separate page. [Page] - Transaction privacyExplain concepts around the privacy of transactions. [Page] - Bitcoin transactions in depthExplain advanced concepts and actions you might have mentioned/linked to above in more depth.
[Page] - Lightning transactions in depthExplain advanced concepts and actions for Lightning you might have mentioned/linked to above in more depth.
[Page] - Managing fundsExplain concepts around managing funds.
[Page] - Case studies (if wanted)Show prototypical designs of common user flows.
|
Beta Was this translation helpful? Give feedback.
-
Payments
RATIONALE
Below is the proposed structure for the payments section — there are first some foundations which will give readers a base to understand further chapters.
The goal with this structure is to provide the reader with a unified way of learning about bitcoin on-chain and lightning. Instead of having to navigate between separate subchapters and comparing the two - the reader is taken through a payments unified user flow. At each step, when relevant the individual considerations, implementation details and constraints are addressed for each technology.
Additionally the idea for "User Flow" section represents the components that map to what developers would use in implementation.
INTRODUCTION
FOUNDATIONS
Privacy
Units & Symbols
Push & Pull Payments
Addresses
Transaction Structure & Lifecycle
Lightning Invoices
USER FLOW
Account Discovery & Scanning
Requesting Payments
Sending
Receiving
Managing Funds
Security
Beta Was this translation helpful? Give feedback.
All reactions