[bisq-network/bisq-docs] [WIP] Produce a 'getting started' guide (#45)

Chris Beams notifications at github.com
Wed May 9 12:05:25 UTC 2018 

cbeams commented on this pull request.

@m52go, I've added a number of review comments here. Some are down at the level of copyediting, and I could do more of that, but have held off, as it's not so important to focus on that now. Basically the structure looks good, and I'd say keep going putting meat on the bones here, and we can do additional rounds of review like this until it's good to go.

>  
-COMING SOON. Subscribe to https://github.com/bisq-network/bisq-docs/issues/37[bisq-network/bisq-docs#37] for updates.
+Bisq is built on some https://bisq.network/philosophy/[serious principles^] and some https://github.com/bisq-network[seriously impressive code^], but it's surprisingly approachable. This guide will help you get up & running quickly.
+
+Here we're going to assume you want to trade a national currency for bitcoin, because that's Bisq's most common use case. But keep in mind Bisq offers trading for a range of altcoins too—the only constraint is that one side of the trade must always be in bitcoin.
+
+== Download & install
+
+To run Bisq, download it from https://bisq.network/downloads/[the Bisq downloads page]. Before installing, it's a good idea to verify the signatures of the downloaded file (https://www.torproject.org/docs/verifying-signatures.html.en[instructions here^]).
+
+[NOTE]
+.Download and install? Why can't I just trade on your website?
+====
+Unlike most exchanges, Bisq doesn't run a central server to receive orders.

The language should always be "offer", not "order". I'm mentioning this just once here, but there are several places throughout the doc that should be updated.

> +Once the installer is done, go ahead and open Bisq. It'll take a few moments to open as it connects to Tor and Bisq's peer-to-peer trading network.
+
+[[[Once it does, it'll ask you to set up a wallet...]]]
+
+[[[discuss first-time application/wallet setup]]]
+
+When that's done, feel free to have a look around Bisq. You can browse buy offers, sell offers, and tweak your account settings.
+
+== Configure a national currency account
+
+Since we're looking to buy bitcoin, let's take a look at the Buy BTC panel. You should see a list of offers, but you'll notice all the orange Buy BTC buttons are disabled:
+
+.Here, all offers are disabled except the one requiring a US Postal Money Order, since there's no account to configure for that method.
+image::before-adding-fiat-account.png[Offers before configuring national currency account]
+
+That's because we haven't set a way to actually pay for the bitcoin we want to buy. Bisq works with several payment methods, so you can pick one you're most comfortable with. Keep in mind that the one you pick will determine:

 - "we haven't yet set up a way" would be a bit better here.
 - "Bisq works with many different payment methods"
 - "so you can choose those you already have access to and are most comfortable using."

> +When that's done, feel free to have a look around Bisq. You can browse buy offers, sell offers, and tweak your account settings.
+
+== Configure a national currency account
+
+Since we're looking to buy bitcoin, let's take a look at the Buy BTC panel. You should see a list of offers, but you'll notice all the orange Buy BTC buttons are disabled:
+
+.Here, all offers are disabled except the one requiring a US Postal Money Order, since there's no account to configure for that method.
+image::before-adding-fiat-account.png[Offers before configuring national currency account]
+
+That's because we haven't set a way to actually pay for the bitcoin we want to buy. Bisq works with several payment methods, so you can pick one you're most comfortable with. Keep in mind that the one you pick will determine:
+
+* which offers you can take (e.g., in the image above, Cash App has many outstanding offers...but if you don't want to use Cash App, and if there are no offers for the payment method you want, you can make your own offer & wait for a taker)
+* how quickly a trade can be completed (e.g., a bank transfer will go through quicker than a money order sent by mail; see https://bisq.network/faq/#5[details here^])
+
+[NOTE]
+.Where is my financial account data stored?

Perhaps stick with "payment account" here instead of introducing the new phrase "financial account", which is not used anywhere in the app or in our other materials.

> +image::before-adding-fiat-account.png[Offers before configuring national currency account]
+
+That's because we haven't set a way to actually pay for the bitcoin we want to buy. Bisq works with several payment methods, so you can pick one you're most comfortable with. Keep in mind that the one you pick will determine:
+
+* which offers you can take (e.g., in the image above, Cash App has many outstanding offers...but if you don't want to use Cash App, and if there are no offers for the payment method you want, you can make your own offer & wait for a taker)
+* how quickly a trade can be completed (e.g., a bank transfer will go through quicker than a money order sent by mail; see https://bisq.network/faq/#5[details here^])
+
+[NOTE]
+.Where is my financial account data stored?
+====
+On your computer *only* (i.e., the computer on which Bisq is installed). Only your trading partner (and your arbitrator, if there's a dispute) will ever see your payment details.
+====
+
+Once you've picked a payment method, go to the Account panel and click "Add New Account." Pick your payment method from the dropdown and enter your details. 
+
+We're going to configure a Venmo account:

In this tutorial, we're going to configure a Venmo account. You can adapt the instructions that follow to your own chosen payment method.

> +
+== Fund your Bisq wallet
+
+We're almost there—last thing: before you buy bitcoin with Bisq, you'll need some bitcoin.
+
+Huh?
+
+Here's why: to encourage fair trades, Bisq requires buyers and sellers to post a security deposit. On the buy side, it's {btc_deposit} BTC, along with a tiny bit more to cover the trading fee & mining fees for the transfers.
+
+[NOTE]
+.I'm new to this and have no bitcoin. How can I get bitcoin for the deposit?
+====
+You can buy bitcoin on a centralized exchange, but if you're interested in Bisq, chances are you might not want to do that.
+
+So what can you do? You've got options: friends, family, bitcoin ATMs, bitcoin meetups (commonly called "Satoshi Squares" but there are many others), vouchers, a site like LocalBitcoins.com, or your https://www.youtube.com/watch?v=GbmWGrQjgTA[friendly neighborhood airdrop^] (although you might need to time-travel to find one of these now!).
+====

The friends and family bit is great here. Bitcoin ATMs and meetups, vouchers are good too. I think I'd drop the "Satoshi Square" bit, as this is basically a historical footnote now. I'd drop LB as they're now more aggressively forcing KYC. And I'd drop the airdrop because it's unlikely to be a helpful route for most readers.

Basically, I'd really promote the family and friends approach. Emphasize how Bisq is peer-to-peer all the way down. You don't have to say a lot to this effect, but rather just make it the most prominent option.

I'd drop or rework the bit about centralized exchanges. The "if you're interested in Bisq, chances are..." bit is pretty cryptic for the uninitiated. If anything, I would move that chunk to a [WARNING] section below the [NOTE] section and expressly warn people NOT to use centralized exchanges to purchase their first bitcoin, and to explain that the reason for this is that most centralized exchanges track your personal information and therefore put you at risk by tying your identity to your bitcoin. Your call, you can just drop it, and this might be too much to try to pull off in a quick sidebar, but it would be valuable if we can get a concise warning to this effect out there.

> +It's *crucial* the information you enter here is correct. Your trading partner can only acknowledge your payment if the they receive a payment from the same account as the account detailed here. Once you've created an account, you cannot edit its information (if you need to make a change, you can delete & add the account again).
+
+The "Account Name" field is an exception: it's just a label only you will ever see, so there's no right or wrong value for it. You can make it whatever you like.
+
+Once you're done, hit the "Save New Account" button and go back to the Buy BTC panel. Offers requiring the payment method you just configured should now be enabled:
+
+.After configuring a payment account: we picked Venmo, so Venmo offers are now enabled.
+image::after-adding-fiat-account.png[Configuring a national currency account]
+
+== Fund your Bisq wallet
+
+We're almost there—last thing: before you buy bitcoin with Bisq, you'll need some bitcoin.
+
+Huh?
+
+Here's why: to encourage fair trades, Bisq requires buyers and sellers to post a security deposit. On the buy side, it's {btc_deposit} BTC, along with a tiny bit more to cover the trading fee & mining fees for the transfers.

The purpose of the security deposit is stronger than "to encourage fair trades". It's "to prevent fraud".

> +It's *crucial* the information you enter here is correct. Your trading partner can only acknowledge your payment if the they receive a payment from the same account as the account detailed here. Once you've created an account, you cannot edit its information (if you need to make a change, you can delete & add the account again).
+
+The "Account Name" field is an exception: it's just a label only you will ever see, so there's no right or wrong value for it. You can make it whatever you like.
+
+Once you're done, hit the "Save New Account" button and go back to the Buy BTC panel. Offers requiring the payment method you just configured should now be enabled:
+
+.After configuring a payment account: we picked Venmo, so Venmo offers are now enabled.
+image::after-adding-fiat-account.png[Configuring a national currency account]
+
+== Fund your Bisq wallet
+
+We're almost there—last thing: before you buy bitcoin with Bisq, you'll need some bitcoin.
+
+Huh?
+
+Here's why: to encourage fair trades, Bisq requires buyers and sellers to post a security deposit. On the buy side, it's {btc_deposit} BTC, along with a tiny bit more to cover the trading fee & mining fees for the transfers.

I'd drop the "tiny" from "along with a tiny bit more". What may be tiny to one may seem like a lot to another. Plus, if we see transaction fee spikes again in the future, these values may not be "tiny" by anyone's estimation.

> +====
+You can buy bitcoin on a centralized exchange, but if you're interested in Bisq, chances are you might not want to do that.
+
+So what can you do? You've got options: friends, family, bitcoin ATMs, bitcoin meetups (commonly called "Satoshi Squares" but there are many others), vouchers, a site like LocalBitcoins.com, or your https://www.youtube.com/watch?v=GbmWGrQjgTA[friendly neighborhood airdrop^] (although you might need to time-travel to find one of these now!).
+====
+
+To find out exactly how much bitcoin you need to execute a specific trade, choose an offer you like. A new "Take Offer" tab will appear with some deal details. Click "Next step" at the bottom. Accept the disclaimer, and you should see a box that looks like this:
+
+<screenshot of box specifying total needed to fund trade>
+[[[caption: In this case, you'll need 0.012184 BTC to start the trade.]]]
+
+Once you've got the bitcoin you need, you can move it into Bisq's built-in wallet. This isn't required, but it'll make trading more convenient because Bisq could automatically transfer the funds it needs (since they'll be stored in a wallet Bisq controls). Otherwise, you'll need to transfer the funds into Bisq every time you start a trade. More on this below.
+
+Now that you've got enough bitcoin for a deposit, you're ready to trade!
+
+== Place a trade

Place an offer to trade

> +====
+You can buy bitcoin on a centralized exchange, but if you're interested in Bisq, chances are you might not want to do that.
+
+So what can you do? You've got options: friends, family, bitcoin ATMs, bitcoin meetups (commonly called "Satoshi Squares" but there are many others), vouchers, a site like LocalBitcoins.com, or your https://www.youtube.com/watch?v=GbmWGrQjgTA[friendly neighborhood airdrop^] (although you might need to time-travel to find one of these now!).
+====
+
+To find out exactly how much bitcoin you need to execute a specific trade, choose an offer you like. A new "Take Offer" tab will appear with some deal details. Click "Next step" at the bottom. Accept the disclaimer, and you should see a box that looks like this:
+
+<screenshot of box specifying total needed to fund trade>
+[[[caption: In this case, you'll need 0.012184 BTC to start the trade.]]]
+
+Once you've got the bitcoin you need, you can move it into Bisq's built-in wallet. This isn't required, but it'll make trading more convenient because Bisq could automatically transfer the funds it needs (since they'll be stored in a wallet Bisq controls). Otherwise, you'll need to transfer the funds into Bisq every time you start a trade. More on this below.
+
+Now that you've got enough bitcoin for a deposit, you're ready to trade!
+
+== Place a trade

And really, it should be "Make an offer to trade" or "Take an offer to trade" to be consistent with our own language elsewhere, and to avoid introducing potentially confusing additional words for the same thing. 'Place' is basically synonymous with 'make', but in the steps that follow, what the user will in fact do is _take an offer_. So we should probably title the section "Take an offer". And I think this is fine, because that is the new user experience we want for people: they show up, they see attractive offers in their currency + payment method of choice, and they take one. It's this "happy path" that we're documenting, and you can of course do a sidebar below about "what if I don't find an offer I want to take?".

> @@ -1,3 +1,123 @@
 = Getting Started with Bisq
+:toc: left
+:sectanchors:
+:btc_deposit: 0.01

Please use dashes vs. underscores in custom Asciidoc attributes like these. This follows conventions with Asciidoc's own built-in attributes (like `figure-caption` below).

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/bisq-network/bisq-docs/pull/45#pullrequestreview-118703561
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20180509/ce322acb/attachment-0002.html>

More information about the github mailing list