At a minimum, this document should help people secure their Bisq wallets by helping them:

• set a password to enable encryption
• save their wallet's seed words so that it can be restored later

Once that's done, perhaps this document could grow into a more general reference on wallet security.

@y3v63n and I created Translator documentation in this repo on my personal github site: https://github.com/arunasurya/bisqtransifex

We would like these three documents to be part of official Bisq documentation. This will help new translators get started with the project and encourage current translators to contribute with their ideas for improving the project.

A little question/suggestion:
The whitepaper is now (relegated) in the archive part of the docs: https://docs.bisq.network/
The whitepaper itself references several other documents:
risk-analysis.pdf, p2p-network.pdf, arbitration-system.pdf, and maybe others.

The links and formats are heterogeneous : google docs, webarchive, ...

I didn't find those (interesting imho) docs neither on github neither on https://docs.bisq.network/ (apologies if I searched badly).
Would it be interesting to rapatriate those docs on those 2 places ? (or it's considered too obsolete ?)

There is already a placeholder link for this guide at https://docs.bisq.network, pointing to https://docs.bisq.network/getting-started.html.

This doc should cover the following essential steps required to get up and trading with Bisq:

1. Download and installation
2. Configuring a national currency account
3. Funding your Bisq wallet (with enough bitcoin to pay your first security deposit)
4. Complete your first trade
5. Getting help
6. Staying in touch

This is of course just the very highest-level outline possible, and there will be things to discuss and decisions to make about how to present each of the bullet points above.

In general, the guide should walk step-by-step through a single, focused use case, and not do a lot of branching into the various options available at each of the bullet points above. For example, in the "Complete your first trade" section, there are four options: the user can (1) make an offer to buy bitcoin, (2) take an offer to buy bitcoin, (3) make an offer to sell bitcoin or (4) take an offer to sell bitcoin. Rather than detail all four (and lose the reader), we should stay focused and detail just one: how to take an offer to buy bitcoin (because this is the easiest and fastest thing for a brand new user to do). We can do sidebars and admonitions to inform the user that the other options exist, though, and as we have more materials available that go into detail about them, we can link to them.

There is also the question of what operating system(s) we should address or focus on in the guide. Like the notes above, I believe we should stay focused and only show instructions and screenshots for one OS (at least for now). Our download statistics tell us that most users are on Windows, but even with that being true, I think we should focus this guide on the Mac. This is for a couple reasons: the first is convenience and practicality, as the author of this guide will probably themselves be using a Mac, and I don't want them to be burdened on this first cut with getting Windows screenshots; the second reason is basically "optics"—the document will simply look and feel better if it's filled with macOS images than if it's filled with Windows images. With that said, though, most screenshots are of the Bisq JavaFX UI, which is essentially the same across all platforms. The only really OS-specific screenshots and instructions are around downloading and installing, and I'm not sure how much we need to spell that out anyway. We writing for a reasonably tech-savvy audience still at this point; I'm not sure we need to document and screenshot the process of downloading and installing from a .dmg.

@m52go plans to begin work on this doc (thus my assigning it to him), and plans to "be his own audience" as he walks through his own first trades with with Bisq.

The first deliverable, then, will be a more detailed outline that we can review. It's fine to iterate on that outline in Slack and in the comments below for now, @m52go, or you can already start working in Asciidoc in your own fork of the repo if you prefer. See https://github.com/bisq-network/bisq-docs#readme for instructions on how to get up and running.

I recently had an experience with someone who told me that he won't trade on Bisq because the general trading fees of 0.0019 BTC are way too high. The reason for that misbelief is, that he googled "bisq fees" & clicked on the whitepaper/fee section (one of the first results). As you all know, in the whitepaper it still says that the fees are exorbitantly high.

Bisq operates with the following fees:

Create offer fee: 0.001 BTC (paid to the arbitrators, mining fee is included)

Take offer fee: same as create offer fee (and also paid to the arbitrators)

Bitcoin mining fee: 0.0003 BTC (A mining fee is included in a transaction three times: Deposit from external wallet, trade, and withdrawal to external wallet. So the sum is 0.0009 BTC)

Security deposit (might be used as arbitration fee): 0.1 BTC, which is returned in whole to the trader after the transaction in case he is not found to have behaved dishonestly. The security deposit from dishonest trader will be used to pay the arbitrator for his efforts. In rare cases half the security deposit of each trader may be collected instead. The active arbitration fee is not related to the size of the trade and does not affect the time required to mediate a dispute as the amount of work an arbitrator must perform is roughly constant even when small amounts are exchanged.

Source: https://docs.bisq.network/exchange/whitepaper.html#fees

I don't want to know how many potential traders got detained to trade by this Google result. The trading fees are way lower and I'd say that for smaller amounts, Bisq is, during a low fee market, one of the cheapest ways to buy Bitcoin as the withdraw fee can be determined on your own.

For that reason, I'd suggest to either delete this page or make clear (with a warning box etc.) that the current trading fees can be found on the wiki.

Please note:
If you are on the whitepaper index and click on fees, you'll get forwarded to the updated wiki (https://bisq.wiki/Trading_fees). But Google still shows the old page with wrong information.

Screenshot of the Google results:

First result doesn't really help. 2nd result is the old whitepaper. 3rd result wrong fees (super old report). 4th result link to correct fees.

• Transcribe https://docs.google.com/document/d/1bl0GxRYDBkvcxzbgc8FR3dtHra-LJ4HmcZnG3itamQw/edit to Asciidoc file in this repository
• Update GDoc to point to the new file
• Update links on bisq-network/website to point to new file

No substantive changes will be made to the document. This will be a transcription-only task. There are elements of the doc that do require substantive updates, but that will happen in a subsequent issue.

Continuing this discussion.

The mandate of the Rules doc is broader, meant to cover rules for all trades (not just F2F) as well as arbitration, so it makes sense to designate 1 place in this repo to discuss the whole thing.

For now the Rules doc is a placeholder (as soon as this is merged). I've linked to this issue at the top of the placeholder for people to get updates.

After the placeholder is merged, I'll open a [WIP] PR that works toward a complete Rules doc.

Upcoming payment methods doc will have details on payment method parameters (maximum trade amounts, trading periods, etc) and account signing for users, but it will lack contributor guidance on the following topics:

• How we think about adding payment methods, payment method hardness scale

• Payment method roles

• How to suggest a new payment method (i.e., issue template)

• Transcribe https://bisq.network/docs/bitsquare.pdf to Asciidoc
• s/Bitsquare/Bisq/g
• Fix obvious inaccuracies, e.g. trading fees
• Set up netlify redirect in bisq-network/website from old pdf => new adoc
• Remove bitsquare.pdf from bisq-network/website

I've noticed that some key docs are hard to find. When we start pushing the DAO through the Bisq program, we want resources to be as easy to find as possible.

What do you think about adding a 'Quick Links' section to the top of the index page, with graphical buttons to stand out from the text links below?

The screenshot below is a quick, rough approximation to show the idea. Graphics can be improved, etc.

I get the following error when I run './gradlew build' inside my /bisq-docs folder.
I used this script to install JAVA: https://github.com/bisq-network/bisq/blob/master/scripts/install_java.sh

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':asciidoctor'.
> Could not resolve all files for configuration ':asciidoctor'.
   > Could not resolve org.codehaus.groovy:groovy-all:2.3.9.
     Required by:
         project : > org.asciidoctor:asciidoctorj-groovy-dsl:1.0.0.Alpha2
      > Could not resolve org.codehaus.groovy:groovy-all:2.3.9.
         > Could not get resource 'https://jcenter.bintray.com/org/codehaus/groovy/groovy-all/2.3.9/groovy-all-2.3.9.pom'.
            > Could not GET 'https://jcenter.bintray.com/org/codehaus/groovy/groovy-all/2.3.9/groovy-all-2.3.9.pom'.
               > sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

* Try:
Run with --stacktrace option to get the stack trace. Run with --info or --debug option to get more log output. Run with --scan to get full insights.

* Get more help at https://help.gradle.org

BUILD FAILED in 1s
1 actionable task: 1 executed

@m52go pointed me to this thread but it's beyond my understanding.

The link
Overview
https://github.com/bisq-network/docs/blob/master/dao-overview.adoc

In Bisq DAO info section is broken
https://bisq.network/dao/

AsciiDoc is a pleasure to write in, but Asciidoctor is drastically limited in format and features—it's just a big wall of text, no matter what. Most notably, there is no way to provide search, and no way to adjust the UI without tons of work.

Instead of wrestling with this limited framework, it makes more sense to me to consider migrating to another framework that's more flexible and feature-rich from the start.

I don't have any specific ideas at the moment, and I don't think this is an urgent priority, but as we have more docs over the next few months (roles docs in particular), the front page will start to get unwieldy.

Therefore I'm creating this issue as a starting point for suggestions and consideration, so that more concrete action can be taken in the next 5-7 months (probably after making a more specific proposal in bisq-network/proposals once details are known).

cc #128

To reflect general practices and conventions on making good requests, and how it works with the DAO.

Per the ongoing discussion in Slack at https://bisq.slack.com/archives/C701A4NNS/p1513844704000273. Further details to come.

Bounty: 200 $BSQ

Hi @cbeams, @ManfredKarrer, and all Bisq enthusiasts :)

Happy Christmas if you're celebrating that

This is a proposal about adding 3 new Github teams to this Bisq "Teams" page at https://github.com/orgs/bisq-network/teams

User Story

As contributors to Bisq documentation (docs) we need 3 Github teams so that:

• the on-boarding of newcomers docs contributors is facilitated
• communications, and notifications/mentions are easier and faster
• the risk of some contributors being left out of the communication loops is reduced
• the noise in the communications is reduce
• the newcomers contributors have a pleasant initial experience. Which in turn increase the retention. Which in turn increase the amount of docs contributors.

Assumptions

• Assumes this proposal is only for docs contributors interested in both using Github and using Github teams. Because some contributors may not be interested in those tools. In other words, the intention of this proposal is not about interfering with other volunteer contributors, or forcing tools or workflows on them. To each their own how, when, where they contribute. The only intent of this proposal is stated in the User Story above.
• Assumes those proposed team names
  1. docs-admins
  1. docs-maintainers
  1. docs-contributors
• Assumes those proposed usage
  1. doc-admins
  Member(s) of this team are interested in administrative tasks related to Bisq documentation. For example member(s) would have access to add or remove members to the doc-admins, doc-maintainers, doc-contributors teams, and doc repo(s).
  1. doc-maintainers
  Member(s) of this team are interested in tasks such as reviewing for approval Bisq doc contributions. For example review for approval the pull requests related to the doc repo(s). I'm assuming that for now only @cbeams needs this? In the future, and when needed members of the docs-admins team could add additional members? Depending on their present admin(s) workload.
  1. doc-contributors
  Member(s) of this team are interested in tasks such as contributing to Bisq docs. For example maintaining the already existing docs. So that they remain fresh and useful. For example if the Bisq software has a new feature or a existing workflow as changed, then update it accordingly. Or contributing new docs.
• Assumes the 3 Github teams would be useful for notification, for example @doc-contributors could be use to notify volunteers asking for their availability & interest to update or create a doc text, screenshots, links, video, etc.
• Assumes the new Github teams are nested under this "contributors" team
• Assumes the new Github teams permissions are visible

Notes

@Francewhoa :) Notes to myself. Docs related to github teams:

• About https://help.github.com/articles/about-teams/
• Notification https://help.github.com/articles/basic-writing-and-formatting-syntax/#mentioning-people-and-teams
• Repo permissions https://help.github.com/articles/repository-permission-levels-for-an-organization/
• EDIT: 2017-Dec-29 reformatted this ticket using User Story and Assumption format

The link to the BSQ transaction on the BSQ explorer doesn't pull up anything meaningful. It might be a problem with the explorer or it might be a bad link.

Link text: that same transaction on a BSQ block explorer
Link destination: https://explorer.bisq.network/tx.html?tx=92df3183d3c60983492983882642145ac0ab8ef93cda07ff57d1f810e34003f6

this could be very helpful for anyone quickly wanting to look up something specific

The Bisq no longer uses the Slack as a discussion infrastructure. In docs is mentioned old information about discussion infrastructure (eg. proposals). It needs to be corrected to not confuse new contributors.

The bisq app for windows lists this message upon start.

The docs however recommend the opposite.
https://github.com/bisq-network/bisq-docs/blob/master/trading-rules.adoc#bitcoin-buyers

Enter the trade ID in payment’s "reason for payment"

If possible, the trade ID should be included in the payment’s "reason for payment" field. The name of this field can vary by payment method; some call it "Message" or "Information for recipient" or similar. Pick the field (if available) that enables the user to tie the payment to the specific trade.

If there is no such field, just send the payment without specifying the trade ID.

Can this be resolved?

Similar to #1, transcribe Bisq DAO - More details and technical specification to /dao/specification.adoc in this repository as a sibling to the /dao/phase-zero.adoc paper.

To reflect integration of the DAO in the process.

To the backup-recovery doc.

Steps to reproduce

1. Using the github interface, fork this repository https://github.com/bisq-network/docs
2. Also fork this parent repository https://github.com/bisq-network
3. Using the first fork above /bisq-network/docs, edit this phase-zero.adoc file
   1. Under "Introduction" section, remove 3 characters, any
4. Still using github interface, send a pull request
   1. During your pull request, on the “Comparing changes” page, notice that the diff is not fully highlighted. This is the challenge. Find screenshot below to clarify the location of this challenge. It's the first time I saw that "glitch" with github.
5. The expected result is that the diff is fully highlighted like in this test with another file. The fully highlighted diff allows to quickly and easily tell what is the suggested edit and its exact location. That's the whole point of a diff, LOL ;) Otherwise it's time consuming to read the whole paragraph and manually try to locate the edit.
6. I was able to reproduce this challenge only when using this forked phase-zero.adoc file. I was not able to reproduce this challenge with any other files within the same forked repository.

Screenshot challenge

Notes

• Related #22 (comment)
• Related tweet by cbeams at https://twitter.com/cbeams/status/944162513482145792

Given I am on https://github.com/bisq-network/docs/blob/master/dao/phase-zero.adoc#slack page
When I click Bisq Slack workspace link
Then I am redirecte to https://bisq-slack.herokuapp.com/
And I see Application error message

intro.adoc : in the last line, the twitter link is wrong
The current intro.adoc contains
https://twitter.com/bisq-network
while the right link is:
https://twitter.com/bisq_network

How to add my coin to the exchange list?

We should document the necessary configuration required for running your own full node.

For example, with the latest release of bitcoin core (0.19.0.1), the -peerbloomfilters configuration option must be set to true, as per https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.19.0.1.md:

To eliminate well-known denial-of-service vectors in Bitcoin Core, especially for nodes with spinning disks, the default value for the -peerbloomfilters configuration option has been changed to false. This prevents Bitcoin Core from sending the BIP111 NODE_BLOOM service flag, accepting BIP37 bloom filters, or serving merkle blocks or transactions matching a bloom filter. Users who still want to provide bloom filter support may either set the configuration option to true to re-enable both BIP111 and BIP37 support or enable just BIP37 support for specific peers using the updated -whitelist and -whitebind configuration options described elsewhere in these release notes. For the near future, lightweight clients using public BIP111/BIP37 nodes should still be able to connect to older versions of Bitcoin Core and nodes that have manually enabled BIP37 support, but developers of such software should consider migrating to either using specific BIP37 nodes or an alternative transaction filtering system. (#16152)

To be located at docs.bisq.network/dao.

Proposed content is here.

Is there a reason the Bisq Telegram Group is not shown on the Getting Started page like the other communications methods such as Slack or the Bisq Subreddit?

Specifically:

"Get help and stay in touch"

"If you get stuck, reach out! There’s a community of people to help you on the Bisq forum, the /r/bisq subreddit, and the Bisq Slack team."

• https://github.com/bisq-network/bisq-docs/blob/master/getting-started.adoc

Along the same lines, the Bisq.network site, such as the Community page, is missing the Telegram group as well.

And the social media icons in the footer of each page.

"JOIN BISQ"

github, twitter, youtube, slack, forum, mailinglist, irc, reddit

When taking an offer for an F2F trade, I was not able to see the offer maker's contact information easily. I could only see it in the "locked funds" window.

Suggestion: It would be great to have the offer maker's and taker's contact info displayed in the same place.

Problem I had

Could be a "user error", but in case anybody else is trying to use build this on a Windows box and encountering the same when trying to build:

Failed to capture snapshot of input files for task ':asciidoctor' property 'sourceDir' during up-to-date check.
> Failed to create MD5 hash for file content.

Environment

This was on an environment using Windows box + PowerShell 3 and then scoop to install gradle and then the gradle plugin for asciidoctor plugin for gradle to build the asciidoctor files which the documentation uses... the result is a bunch of html files translated from the asciidoctor files compiled and saved inside the default build directory for asciidoctor (./build/asciidoctor)...

Fix

To get around it, I just went one level above the root project file (where I git cloned this project) and created a new gradle build file and then ran gradle build in PowerShell from here:

plugins {
    id 'org.asciidoctor.convert' version '1.5.7'
}

asciidoctor {
    sourceDir = file('./bisq-docs')

    resources {
        from(sourceDir) {
            include '**/*.png'
            exclude 'build/**'
        }
    }

    attributes 'source-highlighter': 'coderay',
        icons               : 'font',
        idprefix            : '',
        idseparator         : '-',
        docinfo1            : ''
}

build.dependsOn asciidoctor

This worked for me... changed the sourceDir to the location of the project.

Why did it happen and future fix?

I am not sure. Not very familiar with Gradle, asciidoctor or scoop so not really qualified to say exactly what the problem was! Perhaps somebody else can clarify if this was a red herring, but I read an article suggesting that Windows may have some kind of locking mechanism which stops the part of the build job where it tries to hash the directory to check for updates from working. It's a 2015 article so may be wrong...

Anyhow, if this was the issue then could just move all of the files asciidoctor uses into a subdirectory and leave the gradle.build file where it is... or perhaps there is a parameter or way to specify the build in gradle which overcomes what I encountered.

https://github.com/issues?utf8=%E2%9C%93&q=is%3Aopen+org%3Abisq-network+label%3Abounty
does not navigate to the bounty issues.

From private Keybase chat on Jun 14:

@m52go wrote:

now that v1.6.5 has been out for a while, i think we can shut down docs.bisq.network.
is this something you can do in netlify? i assume it should just be a matter of flipping a switch in their interface.
it might also be good to redirect all requests to the docs subdomain to the wiki (docs.bisq.network/* --> bisq.wiki)

@cbeams wrote:

Will do. Will just do the redirect for now (via Cloudflare) and will shut off Netlify later. It doesn’t cost us anything, no harm in leaving it up.

@m52go wrote:

sounds good. i think the only other factor to consider is that the search engines may continue to index and show docs.bisq.network results (especially google) as long as the site is online, which can be problematic because there's some outdated information on there. but i guess with a redirect in place anyway it may not matter too much.

@cbeams wrote:

correct. with the redirect in place, search engines will no longer be able to index the content (formerly) at docs.bisq.network. The content will remain available at bisq-network-docs.netlify.com, but that url is not referenced anywhere.

Since only the BTC-selling side of a BTC-from-fiat transaction is controlled/tracked by BISQ, what prevents the BTC seller from taking the fiat payment, but denying the fiat payment was ever made (ie. not registering it with BISQ) causing the buyer to get nothing and lose their deposit?

Would love to know the answer,
[email protected]

The Docs recommend the extension Pagesigner for firefox and chrome to prove to the arbitratior that payments did actualy happen

Unfortunately PageSigner seems to be Abandonware:
It is no longer available in the Firefox AddOns Library and it only supports TLS 1.0/1.1, while most banks use TLS 2.0, rendering PageSigner incompatible. see bisq forum

In the Forum, community members recommend Veruv.com. I am unable to evaluate if Veruv is an appropriate replacement but since PageSigner doesn't work at all it may be the only choice to provide evidence of payments done with online banking services.

Based on information in the forum post at [1], write a tutorial that guides users through the process of restoring Bisq from a backup.

The path for this document should be https://github.com/bisq-network/docs/blob/master/exchange/howto/restore-from-backup.adoc, and should follow the format of other existing "howto" tutorials in https://github.com/bisq-network/docs/blob/master/exchange/howto.

See also [2] and [3].

[1] https://forum.bisq.io/t/switching-to-a-new-data-directory/1697
[2] https://forum.bisq.io/t/changing-computers/3365
[3] https://twitter.com/kryptopraxis/status/932664881685377025

Within the DAO specification, there is an invalid link to how to run a full node (https://github.com/bisq-network/exchange/blob/master/doc/rpc.md).

Users can also run themselves a full node either directly from the Bisq application or as a self hosted headless full node. To run a full node requires a Bitcoin Core (bitcoind) full node with RPC enabled. More details on https://github.com/bisq-network/exchange/blob/master/doc/rpc.md[how to run a full node] can be found in the documentation folder of the source code repository.

Provide more detail regarding voting weight

@ManfredKarrer @cbeams @m52go

Voting Stake
Your voting weight is determined by 2 factors: reputation (how much BSQ you’ve earned), and stake (how much of your owned BSQ you allot to your vote) that you specify in your vote transaction.
(...)

Let's Alice earns 10 000 BSQ in cycle 1 and Bob bought 10 000 BSQ in cycle 1.

• What's the reputation equation?
• How is the time calculated? In blocks? 1 day = 144 blocks and so forth?
• In cycle 2, if Alice has only 10 BSQ left after having sold the rest, can she spend 2 on the voting fee, stake 8 and still retain the 10 000 vote weight? What's the minimum value to stake and retain the reputation weight?
• How is Alice's reputation tracked?

This doc can live in the root of this repository, e.g. STYLE.adoc or similar, and in it we can capture styleguide items ranging from Java to Git to GitHub pull request and review style.

I'll leave this issue open for a while, to collect these tips based on real-world changes and reviews of changes across all @bisq-network repositories.

If you find yourself giving or receiving such style tips in the process of going about your daily work, reference this issue (#28) somewhere in your commit, issue or pull request and then later someone can collect them into an actual doc.

Hi,

1. Attempted to accept a trade for bitcoins Dec 22. Transaction id:
   Transaction b50b2834adab6a2cd01df49291751ee0664d5d00002ef3e300e68f15f2f87efa

2. Holding deposit was withheld:
   18GzH11T5h2fpvUoBJDub7MgNJVw3FfqQ8 | 0.00020000 |  
   -- | -- | --

3. The trade failed due to a time-out error. Error message:"A timeout occurred".
   Selected arbitrator: 3b7cft5k4ae6a236.onion:9999

Could you please let me know when to expect the holding deposit to be returned to my account?

Many thanks

Per discussion with @cbeams and @csacher, update https://github.com/bisq-network/docs/blob/master/dao/phase-zero.adoc#how-to-request-compensation

Objectives:

• add note on instant trading accounts for altcoins
• add note BSQ trading fees
• remove title bars from screenshots (to be consistent with new docs...also no reason to shill Windows)

Right now we have good general overviews, but it would be good to have more details for users and contributors to reference various details when the DAO is live.

• "details on the dao" doc covering practical inner workings: proposals (conventions, adding/removing), voting (e.g., stake), vote results (determining correct vote data view), changing parameters, etc.
• technical overview (like this video, but a little more detailed)
• emergency plan

For launch, I will also update the existing docs (e.g., the user guide) to reflect the process and interface at launch. Will make a separate issue for that.

To prevent people from getting old/incorrect information from old docs. Some archived docs rank high in search.

See this thread for reference.