Add atomic swap to docs

[imestin]

Closes #964

[dajohi]

remove the unneeded files

[imestin]

OK, I removed them.

[s-ben]

@imestin looking better. Have made a few suggestions on the wording. I'm not a Subject Matter Expert (SME) on atomic swaps by any means, so can't verify the accuracy of the technical statements (someone else will need to do that), but the technical explanation is already teaching me a bit about atomic swaps :)

[imestin]

I corrected the above mentioned mistakes. I think now is good.

[s-ben]

@imestin just reviewed the latest. Looking much better. The grammar is technically correct, and I think you've added some good technical details. However, comparing this page to the rest of the docs, the style and sentence structure are still quite different. This could be jarring to some readers, and keep the page from getting merged (the bar for advanced technical documentation is high). Also, after digging into the blog @jholdstock linked to and the atomicswap README, I've realized that we already have a lot of content that can be reused. This content has the style and sentence structure we want, so I think the fastest way to complete this page is to redo it reusing existing content where possible, and incorporating the good technical details you've uncovered (e.g. the required opcodes and supported hash functions). Below is a rough outline for how I would do this.

• Basic definition (short paragraph) of atomic swap (borrow from blog)
• Decred-compatible cross-chain atomic swapping (borrow from atomicswap README)
• Theory (borrow from atomicswap README, shorten/summarize if possible, remove any out-of-date statements)
• Use cases (borrow from blog)
• Prerequisites (borrow from blog, make sure info up-to-date)
• Privacy(borrow from blog)
• Integration (check if needs updating)
• Link to atomicswap README for further instructions on using CLI tools.

[imestin]

@s-ben if I would write about integration, I would write about future promises again.
The other points I edited.

review items resolved

[imestin]

Is there anything else to correct?

[s-ben]

Hey @imestin. I'm still seeing a few issues:

• In my review, my main concern was that the style and sentence structure of the new text was not consistent with the rest of the docs. I see that you have kept most of this new text, including three paragraphs for the basic definition (which in my outline is a single "short paragraph"). To give you an example, I'm imagining something more like this, which is the 1st google hit for 'atomic swaps definition'.
• The 'Using Decred’s atomicswap tool' section was left, but this is not in the outline. In the outline I say 'Link to atomicswap README for further instructions on using CLI tools.' at the end of the page.
• The integration section you removed from the outline, but I think it's relevant info to include. The list of major coins is relatively stable, and we can avoid the problem of new coins being added with a disclaimer telling the reader to check the GitHub README for new integrations (or for instruction on adding coins).
• In the 'Prerequisites' section, the bullets need to be capitalized.

[imestin]

hi @s-ben
I removed 'Using Decred’s atomicswap tool', because it's in the end of the page, in the 'Further Information' section. I wasn't sure whether to have that link 2 times in the docs.

So if I go back to my original version, you think it is good? ("An Atomic Swap is a smart contract technology which makes possible to exchange coins from two different blockchains without having to trust any third party, for example a centralized exchange.")

The other 2 things I edited.

My suggestions were implemented

[s-ben]

@imestin, perhaps I'm confused about the state of this PR, but when I pull this branch feature/atomic-swap, I'm only seeing some of the changes.

I removed 'Using Decred’s atomicswap tool', because it's in the end of the page, in the 'Further Information' section. I wasn't sure whether to have that link 2 times in the docs.

When I run this locally, I still see the Using Decred’s atomicswap tool section.

So if I go back to my original version, you think it is good? ("An Atomic Swap is a smart contract technology which makes possible to exchange coins from two different blockchains without having to trust any third party, for example a centralized exchange.")

I think this is a good short description, but when I run locally I still see the old definition. If this change is not in the current branch, please put it in.

As for @dajohi's suggestion of removing the list of supported coins and just linking to the atomicswap GitHub documentation, I think this makes sense. I was on the fence about this myself. I do think we should have a link to the GitHub here though.

[imestin]

Ok, I edited it.

[s-ben]

Just see one minor change and the rest looks good to me.

GitHub repo: https://github.com/decred/atomicswap should be turned into a link: GitHub repo.

[imestin]

ok, done.

[s-ben]

@imestin is there some reason you changed the link text from what I suggested to this?

This is not consistent with the rest of the docs. For repo links, we typically have link text such as repo or GitHub repo. Also, Atomic Swaps on Decred's blog isn't a sentence. I would suggest something like below. Feel free to tweak as you wish, but it needs to be consistent with the style in the rest of the docs.

For more technical information, see the Atomic Swaps Github repo and this technical blog post.

[imestin]

I edited it.

[s-ben]

lgtm

[jholdstock]

I've just given this another look and it has really improved a lot. Great job