Walletwasabi: Build documentation into GitBook static website

Created on 11 Jul 2019  路  17Comments  路  Source: zkSNACKs/WalletWasabi

Issue

As the documentation for Wasabi grows, the relevant markdown files are not easy to navigate for newcomers (for example, the CONTRIBUTING, FAQ, and Dojo files are all found in different directories).

Proposed Solution

I propose to the community the idea of using GitBook to build good looking and easy to navigate documentation out of the markdown files.

As an example of what such a documentation website could look like, I built a mock Wasabi repository with no source code but most of the documentation files, and used GitBook to statically generate the docs website out of them. You can check out the resulting website here: https://wasabi-test.gitbook.io/wasabi-docs-test/

Advantages

GitBook uses webhooks to automatically rebuild the docs website anytime a commit is made on the repo on any of the markdown files concerned. In other words, nothing really changes from the point of view of the developers and the repo maintainers; all the due process still happens on GitHub. The only added bonus is that GitBook builds your documentation website automatically in the background for you. Additionally, good looking docs are just rad; they make us want to work harder at making them more complete, more precise, and more user-friendly.

Are any changes to the repo structure necessary?

Typically, GitBook tracks a directory in the repo called /docs. This is where projects put all markdown files that will be used to build the docs website. Additionally, two files called SUMMARY.md and .gitbook.yaml are required; those provide structure for how one wants the markdown docs files to be put together in GitBook. Check out the repo that generated the mock documentation site to get a sense of how it works.

Can I see more examples of this stuff used in the wild?

For a bigger, more complete example of a good use of GitBook, check out the BTCPay Docs website.

picture thunderbiscuit
❤5 🚀2 👍1

Most helpful comment

Collection of Videos

Zero Link

Introductions and Demos

Tutorials

Developer Interviews

Development

Fun

Please comment on missing videos, or changes to the overall structure.

picture MaxHillebrand on 13 Jul 2019
👍7 👀1

All 17 comments

It is a great idea to have an archive of knowledge that culminates all the documentation that we have so far, and that we will continue to create in the future!

Absolutely, concept ACK!!

I would like to take this as an opportunity to somewhat restructure and stream-line the documentation that we have so far. Yet, I'm not certain what exactly to change, I think we'll figure this out during the process of this project.

I think this is a project for "volunteers", and not necessarily for the "real devs" - division of labor and all. So, may I bring this to the attention of @6102bitcoin & @402PaymentReq & @raindogdance [and other peers] who have already provided invaluable contributions to the documentation.

Let's build this!

MaxHillebrand picture MaxHillebrand on 11 Jul 2019

Good points. I do think that as documentation projects grow in size, they eventually almost take a life of their own, and yes the reviews and issues and commits and pull requests can come to "pollute" the maintainment of the source code in the main repo.

Whether Wasabi is at that stage or not is a separate debate maybe, but I think in general we find that bigger projects then to separate their exhaustive documentation and statically generated docs websites from their source code repository, as is the case for BTCPayServer, which splits its source code repo from its documentation repo on GitHub for a clean "separation of concerns" and development process, and clearly a great finished product.

thunderbiscuit picture thunderbiscuit on 11 Jul 2019
👍2

Thanks for tagging, @MaxHillebrand, would have missed it otherwise.

Agree on the proposal. It makes lots of sense, as well as the argument to separate documentation repo from the code repo, just for the sake of "cleanliness".
The mock up GitBook looks neat!

raindogdance picture raindogdance on 11 Jul 2019

For the sake of completeness, we should note that GitBook is not the only static site generator that can build documentation websites; I simply used it for demonstration purposes. But a good thing about it is that it integrates with any GitHub repo super easily. I just made an account on GitBook and connected it to my repo, and the docs were built almost instantly.

Some tradeoffs to be aware of with GitBook

  1. Only the first "book" is free per account (not necessarily a problem if Wasabi only wants one docs website of course). Note also that their pricing page mentions that the "Startup" account type (one step up from the "free subscription" I used) is free for open source projects and non-profit teams. Wasabi would probably fit that criteria.
  2. It does not support multiple languages yet. So for example, if volunteers offered to translate the docs into other languages, those other languages would have to be their own separate GitBooks. Not quite as clean as having a dropdown menu offering the docs in other languages.

Other notable competitors to GitBook

  1. Docsify
  2. Docusaurus
  3. VuePress

My understanding, however, is that those require a bit more involvement. They also don't offer hosting right off the bat like GitBook does, so you have to figure that out too, and I don't know if the webhook stuff is as easy and cleanly integrated so that it builds automatically when commits are made from the repo. Nothing too bad because all of those can easily be dealt with, but a bit more of a barrier still.

Good docs are ultimately tool agnostic

Also important to remember is that the underlying docs themselves (the markdown files and the repo) are agnostic to what system/tool we use to build the docs website. So in a way the the choice of GitBook vs Docusaurus or whatever is not as big of a commitment as might appear at first glance. One can simply rebuild using another tool and test out options. Of course this is more easily tested and done with a separate docs repo, but not impossible to integrate to the main Wasabi repo either, as long as the devs are into it.

This whole thing does warrant a good amount of planning and discussion for sure to do it smoothly and do it right. Maybe some of the devs in charge of other big documentation projects would have lessons and tips to share.

thunderbiscuit picture thunderbiscuit on 11 Jul 2019

I do agree that a separate repo makes sense, especially considering that the docs should have [?] different maintainers, and to keep the main source code repo clean from distracting commits and files. @nopara73, what do you suggest in this regard?

In regards to the different tools to use, I think it's important to have static pages that pull automatically from the .md files, and to be able to set a theme that fits Wasabi. Seems that GitBook fulfills these requirements, and since we probably only need one book for docs.WasabiWallet.io, I think that this is a good and gratis option. But I do want to point out that Adam said that he had buggy issues with GitBook for Programming the Blockchain

MaxHillebrand picture MaxHillebrand on 12 Jul 2019

Collection of documentation files

General

Development

Installation

Please comment on missing files, or changes to the overall structure.

MaxHillebrand picture MaxHillebrand on 12 Jul 2019
🚀1

Agreed. GitBook is a great way to get going while experiencing the least resistance and shipping results. I also want to point out that GitBook was completely revamped last year, and so I believe that the issues you are referring to were probably associated with what is now called "legacy GitBook", since their repo is 3 years old.

Thanks for the link by the way! I had never seen this resource. Great work.

thunderbiscuit picture thunderbiscuit on 12 Jul 2019
👍1

Collection of Videos

Zero Link

Introductions and Demos

Tutorials

Developer Interviews

Development

Fun

Please comment on missing videos, or changes to the overall structure.

MaxHillebrand picture MaxHillebrand on 13 Jul 2019
👍7 👀1

Is there any good search engine for GitBook?

Can we have a search box where users look for specific key words, and it will show any line in the entire documentation where the word is mentioned?

This plug-in search-pro might work.

MaxHillebrand picture MaxHillebrand on 13 Jul 2019

Wasabi Documentation Structure

Basics

  • Importance of privacy
  • Privacy in Bitcoin [problem in Bitcoin -> solution in Wasabi]
    -- Address reuse -> labeling
    -- Inputs and outputs -> coin selection
    -- Transaction graph -> coin join
    -- Network snooping -> block filters over Tor & full node
  • Getting started
  • Wasabi compared to other Wallets

Installation and Upgrade

  • Download
  • Signature verification
  • Installation
  • Compilation from source
    -- Install NBitcoin
    -- Install Git
    -- Compile Wasabi
  • Deterministic build guide
  • Backend deployment
  • Client deployment

Features

Generate Wallet

  • Label
  • Seed and mnemonic
  • Password

Hardware Wallet

  • Trezor One PIN
  • Trezor One passphrase
  • Trezor passphrase
  • ColdCard
    -- Import skeleton wallet
    -- Build PSBT
    -- Export PSBT
    -- Sign PSBT
    -- Import PSBT
    -- Broadcast PSBT

Load Wallet

  • Difference hot / watch only wallet
  • BIP 158 block filter
  • Download of blocks over tor & full node

Receive

  • HD path
  • SegWit bech32 only
  • Labeling

Send

  • Coin selection
  • Cluster history
  • Transaction fee
  • Password

Coin Join

  • Zero Link
    -- Input registration
    -- Connection confirmation
    -- Output registration
    -- Signing
    -- Broadcasting
  • Anonymity set target
  • Minimum amount and denomination
  • Duration
  • Fees

Development

  • A technical overview of Wasabi Wallet
  • Wasabi coding conventions
  • Security policy
  • Code coverage
  • Manual testing
  • Hardware wallet testing
  • Debug Guide

FAQ and Common Issues

[This is a copy of the current [FAQ](https://github.com/zkSNACKs/WalletWasabi/blob/master/WalletWasabi.Documentation/FAQ.md), but seeing it together with the planned documentation above, I'm not sure if we need to have this separate FAQ at all?]

Pre-Install

  • What is a "coin join"?
  • Do I need to trust Wasabi with my coins?
  • I want to purchase something anonymously. Does coin join happen at the time of payment?
  • Will my coins be fully private after mixing with Wasabi?
  • Can I hurt my privacy using Wasabi?
  • Who is behind Wasabi?

Install

  • How do I install Wasabi?
  • Do I need to run Tor?

Pre-Mix

  • My wallet cannot send to Bech32 addresses - what wallets can I use instead?

Mixing

  • What are the fees?
  • What is the Anonymity Set?
  • How do I change the default number of mixing rounds?
  • Can I mix more than the round's minimum?
  • How do I connect to my own full node?
  • How do I upgrade Wasabi?
  • Why is the minimum mixing amount a weird number?

Post-Mix

  • What do I do now that I have mixed my coins?
  • Can I recombine my mixed coins?
  • Am I safe to send my mixed coins to my hardware wallet?
  • How can I set up my hardware wallet with Wasabi properly?
  • Will I have issues spending my mixed coins?
  • What do I do with small changes?

Meta

  • Where is the coordinator's source code?
  • Does Wasabi have a warrant canary?

Errors

  • Backend will not connect

Dojo

  • Support
  • Issues
  • Contribute Code
MaxHillebrand picture MaxHillebrand on 16 Jul 2019

@MaxHillebrand Just a side note: my name is David Moln谩r.

molnard picture molnard on 16 Jul 2019
🎉1 👍1

@MaxHillebrand I think this Layout looks great. Also I definitely agree:

  • separate repo - That way docs people can watch the repo :)
  • gitbook (or other) if possible, because new users shouldn't really have to use Github for docs :) IMO it doesn't look official to them.
  • a walkthrough guide of the user interface with pictures

My only restructure advice is related to the FAQ:

  • Keep FAQ, if you have an FAQ question that is explained in the docs, link to the main doc.
  • IMO best is a folder in docs, it includes a readme with links to all questions, groups of questions get a .md page. That way you can use the FAQ folder's readme as the FAQ table of contents in Gitbook and users can see all questions together (faster searching).
  • Use a General FAQ: What is Wasabi? What is coin-join? Who is behind Wasabi? Pre-Install sounds like actions the user needs to take before installing.

Excited for the new Wasabi docs :D

britttttk picture britttttk on 17 Jul 2019
🚀1

Really nice work @MaxHillebrand, and thanks @britttttk for the tips. I still can't believe I'm on a thread with such bitcoin heavyweights. 10/10 would recommend!

May I attempt to propose a way forward for this? One idea to roll this out smoothly and in a noncommittal way would be for someone to propose a brand new repo for the docs (maybe under the zkSNACKs org? or maybe just somewhere else, I'm not the best person to know), and we could slowly start contributing to it, without it being _officially_ recognized as being the real docs just yet.

This really wouldn't take anything away from the main source code Wasabi repo, and indeed the two can function side by side for a while. Eventually, if the docs repo is working well and the product is clean, Wasabi could easily have a "soft launch" where they announce the website on Twitter and Telegram as the new "official" docs for Wasabi. But that doesn't have to be right away, and in the meantime if the docs repo is well maintained, Adam and other core devs on the Wasabi source code repo might slowly start to simply refer contributors to this newer docs repo when issues are open that are purely documentation oriented.

I would assume that over time a separation of concerns might emerge, where certain files on the source code repo would become flagged as ready for deprecation upon the soft launch, whereas others would stay active as per their need to be embedded in the source code repository.

Is that something that could work?

thunderbiscuit picture thunderbiscuit on 17 Jul 2019
👍2

Thanks a lot for kicking this off @thunder-B!

I ACK your "soft-launch" idea.

So, the next steps are:

  • @nopara73 please create the zkSnacks/WasabiDoc repository. [As mentioned on Slack, I'd like to offer to be co-maintainer of this repo, so that you don't have to worry about merging the PRs for the doc.]
  • @thunder-B please make the GitBook setup in that repo.
  • @All start writing the doc for any topic in the structure.
MaxHillebrand picture MaxHillebrand on 18 Jul 2019

Aaaand here we go!
First pull request of the new WasabiDoc repository to import all the files mentioned here with the structure proposed here.

Now we can start with the actual work, restructuring and re-writing the documentation!

I suggest we close this issue #1887 and continue the conversation in the issues and PRs of WasabiDoc.

MaxHillebrand picture MaxHillebrand on 18 Jul 2019

Closing this in favor of a whole repo: https://github.com/zkSNACKs/WasabiDoc

nopara73 picture nopara73 on 31 Jul 2019
🎉2

The documentation is now live on docs.wasabiwallet.io !!

MaxHillebrand picture MaxHillebrand on 3 Aug 2019
Was this page helpful?
0 / 5 - 0 ratings

Related issues

MaxHillebrand picture MaxHillebrand  路  3Comments
the-metalworker picture the-metalworker  路  3Comments
gabridome picture gabridome  路  3Comments
yahiheb picture yahiheb  路  3Comments
trading2835 picture trading2835  路  3Comments