Produce a 'getting started' guide #45
Conversation
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This commit squashes 3 other commits I made while working on this the first time. They broke convention & weren't particularly useful, so I combined them.
This comment has been minimized.
This comment has been minimized.
Also set default image directory & disable 'Figure X' image caption prefixes.
|
Good stuff with 72cabda, @m52go. I've just had a quick glance now, but notice that the screenshots are all taken a quite high-res, making the details hard to see. Perhaps you could shrink the screen down, ideally to the default size of the window when it's first launched. If we standardize on doing it that way, then all our documentation will have consistent window dimensions. And things should always be visible enough at those dimensions anyway. i.e. it should be a design constraint that people don't have to stretch the Bisq window beyond its default dimensions just to see some feature of the UI. |
|
Good point @cbeams, didn't think about that. I'll upload new screenshots in my next commit. |
There was a problem hiding this comment.
@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.
getting-started.adoc
Outdated
| [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. |
There was a problem hiding this comment.
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.
getting-started.adoc
Outdated
| .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: |
There was a problem hiding this comment.
- "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."
getting-started.adoc
Outdated
| * 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? |
There was a problem hiding this comment.
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.
getting-started.adoc
Outdated
|
|
||
| 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: |
There was a problem hiding this comment.
In this tutorial, we're going to configure a Venmo account. You can adapt the instructions that follow to your own chosen payment method.
getting-started.adoc
Outdated
| 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!). | ||
| ==== |
There was a problem hiding this comment.
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.
getting-started.adoc
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
The purpose of the security deposit is stronger than "to encourage fair trades". It's "to prevent fraud".
There was a problem hiding this comment.
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.
getting-started.adoc
Outdated
|
|
||
| Now that you've got enough bitcoin for a deposit, you're ready to trade! | ||
|
|
||
| == Place a trade |
There was a problem hiding this comment.
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?".
getting-started.adoc
Outdated
| @@ -1,3 +1,123 @@ | |||
| = Getting Started with Bisq | |||
| :toc: left | |||
| :sectanchors: | |||
| :btc_deposit: 0.01 | |||
There was a problem hiding this comment.
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).
Also, test float layout for 'take an offer' section.
|
Thanks for all that feedback, @cbeams. Last 2 commits integrate your suggestions. As mentioned in the last commit message, all screenshots are placeholders (I got all the screens I needed with my first transaction, but they were all at too high of a resolution, so I need to do another transaction to get usable screenshots). But the body text should be done for the most part. Couple questions:
I'm going to test this with my mom this weekend. Getting her some bitcoin for Mother's Day...only catch is she has to use these instructions to actually carry out the transaction :) Should get some good feedback (she's generally tech-savvy but knows very little about bitcoin), and will get updated screenshots in the process. This thing should be pretty close to complete by the end of the weekend. |
All images are placeholders.
New screenshots taken with lower resolution so they're more readable; also replaced scribble annotation with neater annotation. Copy is slightly tweaked to reflect feedback from real-world test.
Theme of updates: make clear it's about getting a bitcoin DEPOSIT. This wasn't clear in testing.
Add screenshots. Integrate feedback from testing.
|
Latest commit includes some tweaked wording & updated screenshots throughout. I edited the question list in my last comment to reflect lingering concerns. Most notable content change I made was to get rid of the "find the exact amount of BTC you'll need for the security deposit for the deal you want" section and just recommended people get 0.011 BTC to start. I think it comes across way simpler this way, it'll work for any offer a new user is allowed to take, and it leaves wiggle-room for fees. |
|
@m52go, this doc is starting to look really excellent. I just scanned through the latest revision now and will walk through it step by step myself soon to provide feedback. Note there was a broken image toward the bottom (Figure 7.). In the meantime, please keep going with whatever further changes you have in mind. @bisq-network/contributors, everyone is welcome to read and review @m52go's work in progress here. This doc is intended to be our flagship "how to get started with Bisq" guide, so it's well worth getting a number of eyeballs on it. You can find the current latest deploy preview at https://deploy-preview-45--bisq-docs.netlify.com/getting-started.html, though note that the URL will change any with additional commits on this PR branch. |
getting-started.adoc
Outdated
| If you don't already own this bitcoin, you'll need to obtain it. How? You've got options. Do you have any friends or family who could help? 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 an exchange like Coinbase? |
There was a problem hiding this comment.
Coinbase is not an exchange. It's a digital wallet and platform. GDAX is an exchange operated by Coinbase.
There was a problem hiding this comment.
You're right...perhaps I could change "exchange" to something more general like "place" to make it technically correct.
The point of this admonition is to handle thoughts/objections a layman will have at this point in the guide. Most people I've spoken to outside the bitcoin world don't know that...when they think "buy bitcoin" they think "Coinbase" not "GDAX."
getting-started.adoc
Outdated
| [WARNING] | ||
| .How about getting bitcoin through an exchange like Coinbase? | ||
| ==== | ||
| Most centralized exchanges (like Coinbase, Binance, Kraken, etc) track your personal information, putting you at risk by tying your identity with your bitcoin. |
There was a problem hiding this comment.
Coinbase is not an exchange. It's a digital wallet and platform. GDAX is an exchange operated by Coinbase.
getting-started.adoc
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
seriously impressive code is very tongue-in-cheek.
There was a problem hiding this comment.
It is. Readers are free to agree or disagree, but the bigger point here is that they can make up their own mind...i.e., click the link, check out the code, and decide for themselves (i.e., edgy way to convey this is an open-source project).
Ultimately it's about tone. If folks would prefer tone to go in a different direction, it's a discussion we should have.
There was a problem hiding this comment.
I agree that "seriously impressive code" is a bit off, tone-wise. This is something that others can say, but that I'd prefer we do not say in our own official documentation. I like what you're attempting to do in this paragraph, getting the reader excited about the principles and technical foundation, while letting them know that "using Bisq won't hurt" but I'd say take another swing at it. It may not be necessary at all to assume that the reader needs Bisq to be "surprisingly approachable", really. You've done a good job in the doc of detailing what matters and leaving out what doesn't. For example, you just tell the reader to go to the downloads page, get the app and install it. You don't do screenshots there, etc, and treat them like children. Anyone who's going to use Bisq should know perfectly well how to handle that kind of stuff; explaining it would be tone-deaf at best, an insult at worst. So I'd say keep striking that tone: one in which you assume the reader is woke AF about Bitcoin, but possibly still a bit new to the space, and wants to get off to a strong start buying and hodling. They've heard about Bisq, gotten that it's the way to go, and are reading this now here to get the straight no-fluff from us on how to use it. Doesn't mean the doc can't also be friendly and a pleasure to read. It's both of those and should stay that way.
getting-started.adoc
Outdated
|
|
||
| [.right.text-center] | ||
| .Trade complete! | ||
| image::complete-trade.png[Complete trade,400,400] |
getting-started.adoc
Outdated
|
|
||
| == Stay in touch | ||
|
|
||
| If Bitcoin's motto is "be your own bank" then Bisq's motto is "be your own exchange." It's an exciting concept, it's growing fast, and it's something you'll want to follow. |
There was a problem hiding this comment.
it's something you'll want to follow is quite didactic.
There was a problem hiding this comment.
Agree, same basic tone comments as above. This strays from the mark of helping a fellow (perhaps newly born) cypherpunk find their way through the software, to something more didactic, even slightly condescending (though I'm sure you did not mean for it to land that way).
It's definitely good that we point users at the best ways to stay in touch, and even good that we let them know that Bisq is still growing. The motto stuff was a bit of an experiment in the Phase Zero doc. I still generally like it, and there might be a place for it in this doc, but I think it's slightly out of place here in the Stay in touch section.
|
@cbeams from my end this is now a release candidate (pending items listed here). It covers all the content I think it should. With that said, a document like this is never really done, so I'll continue tweaking it, but I think feedback from others is what will get this thing into final form. |
cbeams
changed the title
|
@m52go wrote:
Agreed, I've removed the
Good question. I think we can leave it out. Most wallets these days should have built in mining fee adjustments. I'd say let's add something like this in if people start complaining about it. Otherwise, it's just one more digression, and I think without much need.
ATMs: https://bitcoinatmmap.com/, https://coinatmradar.com/ (I have no experience with these, I just found them listed at https://lopp.net/bitcoin.html). Vouchers: The only thing I know of is https://azte.co, and per https://azte.co/vendors.html, they're still building out their network. Meetups: https://www.meetup.com/topics/bitcoin/
Nothing happens to it. I mean, they should at least transfer it to their Bisq wallet, but it's fine to stay there. The Bisq wallet is a secure, modern wallet like any other, so it's safe there, so long as they have their wallet password in place and seed words secured. So I don't think we need to warn the user about anything. Just instruct them to move the bitcoin to their Bisq wallet or to an external wallet, and voilá, the trade is complete. Note: we shouldn't use the word "deal" where the word "trade" would suffice. Once concept instead of two. |
|
I have a large set of edits to the doc locally, and will push them shortly. Just a heads up that anyone doing further work on the doc will want to wait until I get this done to avoid merge conflicts. |
- Edit the introductory paragrphs to more explicitly state what the
user is going to accomplish by completing this guide
- Use `backticks` instead of "double quotes" to set off named UI
elements, (e.g. buttons and tabs) as literal text
- Capitalize named UI elements accurately, as they are actually
presented in the UI
- Use the term 'screen' over 'panel' when referring to different parts
of the UI
- Use the term 'trade' over 'deal'
- Rework the presentation of "trade wallet" and "escrow" information to
deal with some inaccuracies that were there
- Add several TODOs re screenshots and additional sections
- Drop Telegram from the ways to 'stay in touch', as it's not being
managed by bonded/compensated Bisq contributors.
- Favor the full word 'and' over the use of ampersands ('&').
- Favor spelled-out number words, e.g. 'one' over numerals e.g. '1', as
in "Just 1 more thing".
- Generally edit for style, readability, clarity and consistency of
terminology
There was a problem hiding this comment.
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.
getting-started.adoc
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
- change '&' => 'and' (I missed this in 8913f64 where I changed the others)
getting-started.adoc
Outdated
|
|
||
| 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._ |
There was a problem hiding this comment.
- 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.
getting-started.adoc
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
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.
getting-started.adoc
Outdated
| 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? |
There was a problem hiding this comment.
@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.
getting-started.adoc
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
See the TODO at bottom about this.
getting-started.adoc
Outdated
|
|
||
| == Next steps | ||
|
|
||
| _**TODO**: Remind the user to password-protect their Bisq client and to secure their seed words._ |
There was a problem hiding this comment.
- 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
Accountpanel 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.
|
One other thing I forgot to mention in the review above, @m52go:
|
- Make preface and 'stay in touch' section less editorialized
- Add screenshot in 'download & install' section
- Add references to 'secure your wallet' page (TODO?)
- Add links for ATMs and meetups
- Change 2 screenshots with US Postal Order to Zelle for consistency
- Add sentence in 'stay in touch' section to invite contributors
- Edit minor wording ('& --> and'), 'deal' --> 'trade', etc
|
|
||
| When that's done, the first screen you see should look something like this: | ||
|
|
||
| .Right half of the screen (gold-colored graph) shows outstanding offers you can take to buy bitcoin. That's what we'll be doing in this guide. |
There was a problem hiding this comment.
I wasn't sure how/what to point to with arrows (the right half of the screen is a big area so pointing seemed like it might create more confusion). So I resorted to explaining the relevant part of the screen in the caption...not 100% sold on this approach, so happy to revisit if it's not clear.
|
|
||
| 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. |
There was a problem hiding this comment.
Initially this seemed to make the admonition a bit longer than I'd prefer, but considering it makes perhaps the most important point on the page, I think it's worth it. Great addition.
getting-started.adoc
Outdated
|
|
||
| [IMPORTANT] | ||
| ==== | ||
| Make sure to password-protect your Bisq client and to write down the _seed words_ for your Bisq wallet. Seed words 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. https://docs.bisq.network/secure-wallet.html[Learn more here]. |
There was a problem hiding this comment.
I think linking to a more substantive document is the way to go for this. Otherwise this document will get even longer than it already is...plus securing wallets is so crucial that it deserves to stand as a dedicated page.
Perhaps we can find a way to make that page useful & general enough to serve as advice for new bitcoin users no matter what wallet they use (i.e., to optimize SEO and inbound traffic).
If you agree, I'll get started on it. Then maybe we could remove the secure-wallet links for now so we can push this getting-started document out ASAP and not have to wait for the secure-wallet document to be done first.
getting-started.adoc
Outdated
|
|
||
| You can get updates on https://twitter.com/bisq_network[Twitter^], https://www.facebook.com/bisqnetwork/[Facebook^], and https://www.youtube.com/c/bisq-network[YouTube^]. | ||
|
|
||
| If you really like Bisq, https://docs.bisq.network/contributor-checklist.html[consider contributing]! Even if you're not a developer, there's lots you could do. |
There was a problem hiding this comment.
Figured it worth adding a short bit about contributing (why not). I really want to add something about the DAO here to further spark peoples' interest, but haven't figure out a way to convey it that isn't overkill.
There was a problem hiding this comment.
Instead of
there's lots you could do
Prefer
there is much you can do.
or
there's much to be done.
|
Hello, 1st sentence = original material the only constraint is that one side of each Bisq trade must always be bitcoin. To run Bisq, download and install it from the Bisq downloads page. Optional: before installing, verify the signatures of the Unlike most exchanges, Bisq doesn’t run a centralized server for making and taking offers, so trading on a website isn’t possible. 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 It’ll take a few moments to open as it connects to Tor and syncs with Bisq’s peer-to-peer trading network. If I should proceed in another way, please let me now. I'm very far from a great github expert. :) |
|
@m52go, this looks great now, and I think we're close to ready to merge. My last suggestions:
|
|
@m52go, I'd like to merge and announce this doc tomorrow (Monday) morning. Do you have time to address my latest comments? If not, we could still merge and you could follow up afterward. Better at this point to get this out there, I think. |
- Add new placeholder page for securing wallet (created issue #58 pending its completion). - Took out bit about verifying Bisq signatures. It's something I will revisit, but it's not critical right now. - Took out "Feel free to take a look around" bit...the big screenshot above made it easy to miss, and it didn't serve much of a purpose anyway.
- Add bit about backing up application directory. - Also change 'save' to 'write down' in a couple places (wrt to seed words). - Remove under-construction message at the bottom.
This ensures that links work everywhere, even when html output hasn't been generated, which is the case when using Asciidoctor.js in the browser for instantaneous rendering of changes to the text. See https://asciidoctor.org/docs/user-manual/#inter-document-cross-references
With link to document source in GitHub. Also, consolidate 'Get help' and 'Stay in touch' sections in order to cut down on these extra sections at the bottom of the document, and because the line between getting help and staying in touch isn't so clear cut (Slack, for example is really both).
|
Merging as complete. Thanks @m52go for all your work here! I'll tweet about the new doc shortly after publication. |
Produce a 'getting started' guide
Goal of this document is described in #37. This PR is a revised version of #43. Feedback welcome!