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

Wed May 16 18:55:51 UTC 2018

cbeams requested changes on this pull request.

NACK. @m52go, you'll see that I did quite a substantive editing pass in 8913f64; please give the full commit comment and diff a thorough review  there, and please ask any questions, provide any feedback you see fit. I prefer to "just do stuff" where it would be faster than writing what should be done, so nothing is set in stone just because I committed it here, but it does all reflect my best editorial sensibilities.

You'll also see a number of review comments here as well, most with checkboxes you can tick off as you go for convenience.

Again, I think this is really shaping up into something valuable for users, and I think we're very close now to something we can go live with. Thanks for everything so far.

Additional reviews and feedback from other @bisq-network/contributors is still welcome! Thanks @rex4539 for jumping in already.

>  
-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.

- [ ] change '&' => 'and' (I missed this in 8913f64 where I changed the others)

> +.Why do I need to download software? Why can't I just trade on your website?
+====
+Unlike most exchanges, Bisq doesn't a centralized server for making and taking offers, so trading on a website isn't possible.
+
+Instead, Bisq manages offers to trade using a peer-to-peer network—a global network of people who are also running Bisq on their own computers.
+
+This is good news for users, because centralized services are easy to monitor, block and shut down, while peer-to-peer networks like BitTorrent, Bitcoin and Bisq are difficult to surveil, censor and hack.
+
+This means that if you want to use the Bisq Network, you've got to download and run the software too!
+====
+
+Once the installer is finished, go ahead and open Bisq. It'll take a few moments to open as it connects to Tor and syncs up with Bisq's peer-to-peer trading network.
+
+When that's done, feel free to have a look around. You can browse existing offers to buy and sell bitcoin. The first screen you see should look something like this:
+
+_**TODO**: SCREENSHOT, possibly with boxes and arrows pointing to offers to buy vs offers to sell, to help the reader understand the offer book they're looking at._

- [ ] This TODO, if you agree. I think it would help orient the user, give an initial warm fuzzy that they're in the right place and have gotten everything set up. Plus, the offer book and list of offers to buy and sell are notoriously unintuitive to new users.

> +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.
+
+In this guide, we're going to assume you want to buy bitcoin in exchange for a national currency, since that's how most people get started with Bisq. Specifically, we'll walk through the steps to buy bitcoin with US dollars, using a popular payment method called _Zelle_. Keep in mind, though, that Bisq offers support for trading all national currencies and dozens of different cryptocurrencies and tokens—the only constraint is that one side of each Bisq trade must always be bitcoin.
+
+== Download & install
+
+To run Bisq, download and install it from https://bisq.network/downloads/[the Bisq downloads page^]. _Optional:_ before installing, verify the signatures of the downloaded file (https://www.torproject.org/docs/verifying-signatures.html.en[instructions here^]) to be sure the file you downloaded is genuine.
+
+[NOTE]
+.Why do I need to download software? Why can't I just trade on your website?
+====
+Unlike most exchanges, Bisq doesn't a centralized server for making and taking offers, so trading on a website isn't possible.
+
+Instead, Bisq manages offers to trade using a peer-to-peer network—a global network of people who are also running Bisq on their own computers.
+
+This is good news for users, because centralized services are easy to monitor, block and shut down, while peer-to-peer networks like BitTorrent, Bitcoin and Bisq are difficult to surveil, censor and hack.

I added this line in 8913f64. Feedback welcome. Seems like a good opportunity to drive home _why_ Bisq does things this way, _why_ it's valuable to go through the "extra work" of not being able to just trade on a website.

> +
+.After configuring a payment account: we picked Zelle, so Zelle offers are now enabled.
+image::after-adding-fiat-account.png[Configuring a national currency account]
+
+== Fund your Bisq wallet
+
+There's just one more thing to do before we can trade with Bisq: we need to send enough bitcoin to our Bisq wallet to cover a security deposit as well as trading and mining fees.
+
+To prevent fraud, Bisq requires both buyers and sellers to post a security deposit in bitcoin for every trade. On the buyer's side, this amount is usually {btc-deposit} BTC, plus with a trading fee and mining fees for the Bitcoin transactions involved in each trade.
+
+As of this writing, that means you'll need {btc-deposit-plus-fees} BTC.
+
+If you don't already own this much bitcoin, you'll need to obtain it. How? You've got options. Friends and family are often the best option—simply buy a small amount of bitcoin directly and in person from someone you trust. Otherwise, you can try a local bitcoin ATM (many don't require ID for small transactions), vouchers, or bitcoin meetups/events.
+
+[WARNING]
+.How about getting bitcoin through a centralized exchange like Coinbase?

@rex4539 and @m52go, I changed this back from 'platform' to 'exchange', and you'll see in the paragraph below I use the phrase "platforms and exchanges". I agree with your point @rex4539 that Coinbase is not technically an exchange, but most readers are going to be most familiar with the phrase "centralized (bitcoin) exchange", and I think invoking that here is good from a purely pragmatic perspective.

> +
+As of this writing, that means you'll need {btc-deposit-plus-fees} BTC.
+
+If you don't already own this much bitcoin, you'll need to obtain it. How? You've got options. Friends and family are often the best option—simply buy a small amount of bitcoin directly and in person from someone you trust. Otherwise, you can try a local bitcoin ATM (many don't require ID for small transactions), vouchers, or bitcoin meetups/events.
+
+[WARNING]
+.How about getting bitcoin through a centralized exchange like Coinbase?
+====
+Most centralized platforms and exchanges (like Coinbase, Binance, Kraken, etc) track your personal information, putting you at risk by tying your identity to the bitcoin you buy and sell there. And because Bitcoin transactions are public and easily traceable, this means that potentially _all_ of your future transactions involving those bitcoin can be traced back to you.
+
+Bisq is built from the ground up to avoid this privacy fiasco, so we strongly recommend avoiding centralized exchanges and to get your first bitcoin through one of the other channels mentioned above.
+====
+
+Once you've gotten enough bitcoin for your security deposit and fees, you can move it into Bisq's built-in wallet. This isn't strictly required, but it'll make trading more convenient since the security deposit & fees you need to accept an offer will be readily available when making or taking an offer.
+
+IMPORTANT: Make sure to password-protect your Bisq client and to write down the _seed words_ for your Bisq wallet. Seed words will allow you to recover the funds in your wallet in case of disaster. You'll find them in the `Wallet seed` section of the `Account` screen. Don't worry, we'll remind you about this again at the end of this tutorial so you don't forget.

See the TODO at bottom about this.

> +
+[.right.text-center]
+.Trade complete.
+image::complete-trade.png[Complete trade,400,400]
+
+When the seller receives your payment, they'll mark it as received in Bisq. Bisq will then complete the trade by releasing the bitcoin being traded to you along with your security deposit.
+
+You can keep your new bitcoin in your built-in Bisq wallet by clicking `Move Funds to Bisq Wallet` or send it elsewhere by clicking `Withdraw to External Wallet`.
+
+--
+
+Congratulations. You've just completed your first trade on Bisq!
+
+== Next steps
+
+_**TODO**: Remind the user to password-protect their Bisq client and to secure their seed words._

- [ ] Fill this in one way or another. I'm open to how we want to do this; ideally we'd have another short guide, e.g. 'Securing your Bisq client' to link to, and I'd prefer not to go into a step-by-step digression here when we're so close to the end of the doc. Ideas welcome, but if you want to take the easy way out and just refer the user to the relevant sections of the `Account` panel to fend for themselves, that's fine. The main point is that we really admonish the user to do this, now that they have some actual value stored in Bisq.

-- 
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-120769897
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20180516/c5a608f0/attachment-0002.html>