<p>For posterity, here is the Slack conversation between <a class="user-mention" data-hovercard-user-id="431064" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/blabno">@blabno</a> and me (<a class="user-mention" data-hovercard-user-id="301810" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/cbeams">@cbeams</a>) that led to this iteration of the doc. It describes the history and design motivations behind this kind of 'getting started guide' effort. From <a href="https://bisq.slack.com/archives/C75ABAU9J/p1526035993000053" rel="nofollow">https://bisq.slack.com/archives/C75ABAU9J/p1526035993000053</a>:</p>
<blockquote>
<p>bernard [12:53 PM]<br>
<a class="user-mention" data-hovercard-user-id="301810" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/cbeams">@cbeams</a> is this the level of detail you would like to see <a href="https://github.com/blabno/bisq-docs/blob/feature/http-api/exchange/howto/http-api.adoc">https://github.com/blabno/bisq-docs/blob/feature/http-api/exchange/howto/http-api.adoc</a> ?</p>
<p>cbeams [1:39 PM]<br>
Thanks so much for posting this early-ish, <a class="user-mention" data-hovercard-user-id="431064" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/blabno">@blabno</a>. This looks like the beginning of what could be a good User Guide / User Manual sort of doc (as you refer to it above), but it’s different than what I have in mind when I talk about a “Getting Started Guide”.</p>
<p>Getting Started Guides are about providing step by step instructions to accomplish a specific use case that results in working code.</p>
<p>You can see how we did this at Spring by browsing through the Getting Started Guides at <a href="https://spring.io/guides" rel="nofollow">https://spring.io/guides</a>. It’s good to look through the full list there, to get a sense of what I mean by specific use cases, but in particular, look at the “Getting Started building a RESTful Web Service” guide at <a href="https://spring.io/guides/gs/rest-service/" rel="nofollow">https://spring.io/guides/gs/rest-service/</a>.</p>
<p>We followed the same approach at Gradle, and again you can browse the available Getting Started guides at <a href="https://gradle.org/guides/" rel="nofollow">https://gradle.org/guides/</a>.</p>
<p>Have a look in particular at <a href="https://guides.gradle.org/building-java-libraries/" rel="nofollow">https://guides.gradle.org/building-java-libraries/</a><br>
Notice when comparing each of these guides, they all have a very similar structure. They are focused on a specific use case, they tell the user what they’re going to build, what they’re going to need, and then provide the simplest possible step by step instructions to fulfill accomplish that use case. They always end up with working code. And in case there’s any trouble, the end result of the code they should create in the step by step process is available as a standalone repository (it would be fine in our case if it were just a directory under the bisq-api repository).<br>
This is similar to what we’re doing with the Getting Started with Bisq guide underway at <a class="issue-link js-issue-link" data-error-text="Failed to load issue title" data-id="314795018" data-permission-text="Issue title is private" data-url="https://github.com/bisq-network/bisq-docs/issues/37" href="https://github.com/bisq-network/bisq-docs/issues/37">#37</a></p>
<p>You can just jump to the current deploy preview at <a href="https://deploy-preview-45--bisq-docs.netlify.com/getting-started.html" rel="nofollow">https://deploy-preview-45--bisq-docs.netlify.com/getting-started.html</a> to have a direct look at the structure.<br>
This guide is a little different than the Getting Started Guides I’ve called out above, because this one isn’t about writing code to accomplish a given task, it’s about following a set of steps to accomplish completing your first trade on Bisq,<br>
but the principles are the same. The guide should be laser-focused on getting the reader from zero to hero. It’s a focused guide, not a general reference.<br>
so it tells the user what they’re going to do, what they’re going to need, and then walks them step by step through exactly how to get that done.<br>
Along the way, there’s plenty of room for sidebars that provide context and color,<br>
but things should never digress into a general reference / User Manual style experience. The goal is to get the reader in and out as quickly as possible, wanting to come back for more.<br>
the idea with these guides is that you write a lot of them.<br>
Notice how there are very many of them in both the Gradle and Spring cases<br>
So you can imagine that we would have similar guides for how to switch data directories, do backups, or whatever other use cases are worth documenting in this way with Bisq (none of that is clear yet… the only thing that’s clear is that we need at least one Getting Started with Bisq guide that focuses on completing the first, simplest possible use case of taking an existing offer), but we’ll see.<br>
And it’s not obvious whether we’d want to have lots of guides around the API, but having at least one is a no-brainer for me. Something that shows the user, step by step, how to implement the simplest possible trading bot.<br>
>From there, the user will be hungry to come back for more,<br>
they’ll be ready to consume more general purpose, reference-style documentation,<br>
because they’ll have had a pleasant, guided, and ultimately successful experience getting everything set up for the first time.<br>
Everything after that is easy by comparison, it’s all just tweaking stuff, it’s figuring out which other API calls are available, etc. And that’s where reference documentation is useful.<br>
One other thing: please drop all the subdirectories, and just work on the file in the root directory of the bisq-docs repository. <code>getting-started-http-api.adoc</code> would be fine.<br>
I started things off with the deeper directory structure you’re following suit with,<br>
but as things have progressed, I’ve decided to keep everything flat, at least for now,<br>
and to organize and group things “virtually” via the <code>index.adoc</code> file<br>
I have a much larger outline / ToC for the docs site on its way,<br>
but ultimately, we don’t know what directory structure (if any) is going to make sense in the end,<br>
so I just want to keep everything flat.<br>
Basically think of the whole site like a wiki that is evolving toward becoming a comprehensive Bisq Network operator’s manual.<br>
And like (most) wikis, it has a flat namespace.<br>
Allows for maximum flexibility in the future with structuring things,<br>
and minimizes the need to do a lot of relative pathing when linking to other files.<br>
One of the best things about focusing on Getting Started Guides like I’ve described them above is that it forces the team building the software to really put themselves in the shoes of those who are going to <em>use</em> the software. It forces you to think about things like “what <em>is</em> the most basic use case for the Bisq HTTP API?” “What <em>is</em> the simplest possible trading bot that could work?” “What are the bare minimum set of things the user will need and steps the user must take to actually build such a thing?”<br>
I do not know the answers to any of these questions, and sometimes it is a judgment call. The very first guide we wrote for the Getting Started Guides effort on the Spring team was indeed the “Getting Started building a RESTful Web Service” guide you saw above, because at the time (2013), we were dead-certain that there were zillions of developers typing “how to build a RESTful web service with Spring” into Google. We wanted to write the definitive answer to that question, provide users with precisely what they needed, and shoot right to the top of the Google search rankings in the process. And that’s exactly what happened.<br>
What we want to do here, is imagine, what is the Getting Started Guide that would provide the most value to someone who wants to start scripting their Bisq node to do automated trading? I’m already making an assumption here when I say that, i.e. that what people would want to do with this API is automate trading, as opposed to communicate manually with their Bisq node over a webapp or mobile app.<br>
But I’m making that assumption, because I think that most people aren’t going to try to build bisq-mobile (like you are)—that’s a huge endeavor.<br>
I think it’s reasonable to assume that a fairly large number of users would want to write a trading bot though,<br>
indeed that’s the whole thing that got this effort going in the first place.</p>
<p>bernard [2:02 PM]<br>
What I've described is complete trade flow which is a complete use case for Bisq I guess</p>
<p>cbeams [2:02 PM]<br>
so what is the simplest possible trading bot? what language should it be written in to be a most effective demonstration? Java, Python?<br>
there are tons of such decisions to make,<br>
and while the resulting Getting Started Guide ends up being super lean, short and very quick and pleasant to follow, that’s only because the team who wrote it did the hard work and thinking to design a guide that would be relevant and as minimal as possible, etc.<br>
As a reader, I wouldn’t think that what I’m supposed to do with that doc is follow it step by step, and, as it is now, I wouldn’t have any reason to believe that if I did follow every step, that I would end up with working code. I wouldn’t know that what I’m doing along the way is implementing a “complete trade flow”, because the doc never told me that’s what I’m going to do. I would look at that doc as something more like a collection of useful reference notes about how to do different things, but it wouldn’t be obvious to me that it’s a joined-up, step-by-step focused experience.<br>
When I say simplest possible bot, I mean like <em>the simplest possible bot</em>:<br>
e.g. a bot that listens for all incoming offers and prints out offers to sell BTC at less than a given distance from market price.<br>
DEAD simple.<br>
If I have to set up regtest, deal with arbitration, mess with docker, etc, I’m going to walk away<br>
unless I’m super motivated.<br>
If I follow a guide that ends up in me writing a super simple bot, and the whole thing takes me ~15 minutes,<br>
I’m going to be effing thrilled<br>
and hungry for more<br>
I’ll be happy to take on more ambitious stuff,<br>
because I have a base to build on<br>
and a metal model of the project that I like</p>
<p>bernard [2:08 PM]<br>
Ok, I'll create several tiny docs that allow user do to something on mainnet, so that they could do it out of the box</p>
<p>cbeams [2:08 PM]<br>
and basically a positive emotional experience.<br>
sure, one is enough to start with.<br>
in my experience, these are deceptively difficult for people to write the first time around<br>
making things simple is never easy<br>
so I’d nail one down<br>
and then move on to the next<br>
don’t try to do several at once.<br>
By the way, I’ll happily be the guinea pig to walk through that first doc. I’d really love to write my own trading bot for Bisq!<br>
For this to really work, it’ll mean that I need to build your #bisq-desktop fork from source, because that’s the only one that will have the <code>--httpApiEnabled</code> flag available. This is fine, and you should definitely write the doc that way, i.e. with literally whatever steps are necessary to build a functional trading bot. When everything is ready for primetime and we integrate the http api into the canonical bisq-network/bisq-desktop repository, that step in the doc will go away, or get a lot simpler, of course. But in the meantime, if it actually spells out working instructions, that means that anyone can use the doc as soon as it’s written. We can start getting feedback on this stuff even before officially integrating it, which would be excellent.</p>
<p>bernard [2:16 PM]<br>
Thank you for quick feedback Chris. I'll try to get it written ASAP</p>
<p>cbeams [2:16 PM]<br>
Killer. Thank you.</p>
<p>bernard [2:18 PM]<br>
Yes, that was another part that was making the writing hard. I want sure how the instructions should be cause I was writing it with integration in mind. I'll write it against current bisq-api code</p>
<p>cbeams [2:19 PM]<br>
Yeah, just write it according to whatever I literally must do right now to get up and running. Then the doc should get simpler over time as more stuff gets integrated, etc.<br>
Feel free, by the way to fully steal the format from the Spring and Gradle guides.<br>
They are nearly identical in structure for a reason <g-emoji class="g-emoji" alias="slightly_smiling_face" fallback-src="https://assets-cdn.github.com/images/icons/emoji/unicode/1f642.png">🙂</g-emoji></p>
</blockquote>

<p style="font-size:small;-webkit-text-size-adjust:none;color:#666;">—<br />You are receiving this because you are subscribed to this thread.<br />Reply to this email directly, <a href="https://github.com/bisq-network/bisq-docs/pull/54#issuecomment-389822839">view it on GitHub</a>, or <a href="https://github.com/notifications/unsubscribe-auth/AkpZtoagAAZbR97yAKkeDAXehMZTbanNks5tzVKqgaJpZM4UCs7J">mute the thread</a>.<img src="https://github.com/notifications/beacon/AkpZttgdk0Jj3WnpHrhkoSqcvHiuGJDyks5tzVKqgaJpZM4UCs7J.gif" height="1" width="1" alt="" /></p>
<div itemscope itemtype="http://schema.org/EmailMessage">
<div itemprop="action" itemscope itemtype="http://schema.org/ViewAction">
  <link itemprop="url" href="https://github.com/bisq-network/bisq-docs/pull/54#issuecomment-389822839"></link>
  <meta itemprop="name" content="View Pull Request"></meta>
</div>
<meta itemprop="description" content="View this Pull Request on GitHub"></meta>
</div>

<script type="application/json" data-scope="inboxmarkup">{"api_version":"1.0","publisher":{"api_key":"05dde50f1d1a384dd78767c55493e4bb","name":"GitHub"},"entity":{"external_key":"github/bisq-network/bisq-docs","title":"bisq-network/bisq-docs","subtitle":"GitHub repository","main_image_url":"https://cloud.githubusercontent.com/assets/143418/17495839/a5054eac-5d88-11e6-95fc-7290892c7bb5.png","avatar_image_url":"https://cloud.githubusercontent.com/assets/143418/15842166/7c72db34-2c0b-11e6-9aed-b52498112777.png","action":{"name":"Open in GitHub","url":"https://github.com/bisq-network/bisq-docs"}},"updates":{"snippets":[{"icon":"PERSON","message":"@cbeams in #54: For posterity, here is the Slack conversation between @blabno and me (@cbeams) that led to this iteration of the doc. It describes the history and design motivations behind this kind of 'getting started guide' effort. From https://bisq.slack.com/archives/C75ABAU9J/p1526035993000053:\r\n\r\n\u003e bernard [12:53 PM]\r\n\u003e @cbeams is this the level of detail you would like to see https://github.com/blabno/bisq-docs/blob/feature/http-api/exchange/howto/http-api.adoc ?\r\n\u003e \r\n\u003e cbeams [1:39 PM]\r\n\u003e Thanks so much for posting this early-ish, @blabno. This looks like the beginning of what could be a good User Guide / User Manual sort of doc (as you refer to it above), but it’s different than what I have in mind when I talk about a “Getting Started Guide”.\r\n\u003e \r\n\u003e Getting Started Guides are about providing step by step instructions to accomplish a specific use case that results in working code.\r\n\u003e \r\n\u003e You can see how we did this at Spring by browsing through the Getting Started Guides at https://spring.io/guides. It’s good to look through the full list there, to get a sense of what I mean by specific use cases, but in particular, look at the “Getting Started building a RESTful Web Service” guide at https://spring.io/guides/gs/rest-service/.\r\n\u003e \r\n\u003e We followed the same approach at Gradle, and again you can browse the available Getting Started guides at https://gradle.org/guides/.\r\n\u003e \r\n\u003e Have a look in particular at https://guides.gradle.org/building-java-libraries/\r\n\u003e Notice when comparing each of these guides, they all have a very similar structure. They are focused on a specific use case, they tell the user what they’re going to build, what they’re going to need, and then provide the simplest possible step by step instructions to fulfill accomplish that use case. They always end up with working code. And in case there’s any trouble, the end result of the code they should create in the step by step process is available as a standalone repository (it would be fine in our case if it were just a directory under the bisq-api repository).\r\n\u003e This is similar to what we’re doing with the Getting Started with Bisq guide underway at https://github.com/bisq-network/bisq-docs/issues/37\r\n\u003e \r\n\u003e You can just jump to the current deploy preview at https://deploy-preview-45--bisq-docs.netlify.com/getting-started.html to have a direct look at the structure.\r\n\u003e This guide is a little different than the Getting Started Guides I’ve called out above, because this one isn’t about writing code to accomplish a given task, it’s about following a set of steps to accomplish completing your first trade on Bisq,\r\n\u003e but the principles are the same. The guide should be laser-focused on getting the reader from zero to hero. It’s a focused guide, not a general reference.\r\n\u003e so it tells the user what they’re going to do, what they’re going to need, and then walks them step by step through exactly how to get that done.\r\n\u003e Along the way, there’s plenty of room for sidebars that provide context and color,\r\n\u003e but things should never digress into a general reference / User Manual style experience. The goal is to get the reader in and out as quickly as possible, wanting to come back for more.\r\n\u003e the idea with these guides is that you write a lot of them.\r\n\u003e Notice how there are very many of them in both the Gradle and Spring cases\r\n\u003e So you can imagine that we would have similar guides for how to switch data directories, do backups, or whatever other use cases are worth documenting in this way with Bisq (none of that is clear yet… the only thing that’s clear is that we need at least one Getting Started with Bisq guide that focuses on completing the first, simplest possible use case of taking an existing offer), but we’ll see.\r\n\u003e And it’s not obvious whether we’d want to have lots of guides around the API, but having at least one is a no-brainer for me. Something that shows the user, step by step, how to implement the simplest possible trading bot.\r\n\u003e From there, the user will be hungry to come back for more,\r\n\u003e they’ll be ready to consume more general purpose, reference-style documentation,\r\n\u003e because they’ll have had a pleasant, guided, and ultimately successful experience getting everything set up for the first time.\r\n\u003e Everything after that is easy by comparison, it’s all just tweaking stuff, it’s figuring out which other API calls are available, etc. And that’s where reference documentation is useful.\r\n\u003e One other thing: please drop all the subdirectories, and just work on the file in the root directory of the bisq-docs repository. `getting-started-http-api.adoc` would be fine.\r\n\u003e I started things off with the deeper directory structure you’re following suit with,\r\n\u003e but as things have progressed, I’ve decided to keep everything flat, at least for now,\r\n\u003e and to organize and group things “virtually” via the `index.adoc` file\r\n\u003e I have a much larger outline / ToC for the docs site on its way,\r\n\u003e but ultimately, we don’t know what directory structure (if any) is going to make sense in the end,\r\n\u003e so I just want to keep everything flat.\r\n\u003e Basically think of the whole site like a wiki that is evolving toward becoming a comprehensive Bisq Network operator’s manual.\r\n\u003e And like (most) wikis, it has a flat namespace.\r\n\u003e Allows for maximum flexibility in the future with structuring things,\r\n\u003e and minimizes the need to do a lot of relative pathing when linking to other files.\r\n\u003e One of the best things about focusing on Getting Started Guides like I’ve described them above is that it forces the team building the software to really put themselves in the shoes of those who are going to *use* the software. It forces you to think about things like “what _is_ the most basic use case for the Bisq HTTP API?” “What _is_ the simplest possible trading bot that could work?” “What are the bare minimum set of things the user will need and steps the user must take to actually build such a thing?”\r\n\u003e I do not know the answers to any of these questions, and sometimes it is a judgment call. The very first guide we wrote for the Getting Started Guides effort on the Spring team was indeed the “Getting Started building a RESTful Web Service” guide you saw above, because at the time (2013), we were dead-certain that there were zillions of developers typing “how to build a RESTful web service with Spring” into Google. We wanted to write the definitive answer to that question, provide users with precisely what they needed, and shoot right to the top of the Google search rankings in the process. And that’s exactly what happened.\r\n\u003e What we want to do here, is imagine, what is the Getting Started Guide that would provide the most value to someone who wants to start scripting their Bisq node to do automated trading? I’m already making an assumption here when I say that, i.e. that what people would want to do with this API is automate trading, as opposed to communicate manually with their Bisq node over a webapp or mobile app.\r\n\u003e But I’m making that assumption, because I think that most people aren’t going to try to build bisq-mobile (like you are)—that’s a huge endeavor.\r\n\u003e I think it’s reasonable to assume that a fairly large number of users would want to write a trading bot though,\r\n\u003e indeed that’s the whole thing that got this effort going in the first place.\r\n\u003e \r\n\u003e bernard [2:02 PM]\r\n\u003e What I've described is complete trade flow which is a complete use case for Bisq I guess\r\n\u003e \r\n\u003e cbeams [2:02 PM]\r\n\u003e so what is the simplest possible trading bot? what language should it be written in to be a most effective demonstration? Java, Python?\r\n\u003e there are tons of such decisions to make,\r\n\u003e and while the resulting Getting Started Guide ends up being super lean, short and very quick and pleasant to follow, that’s only because the team who wrote it did the hard work and thinking to design a guide that would be relevant and as minimal as possible, etc.\r\n\u003e As a reader, I wouldn’t think that what I’m supposed to do with that doc is follow it step by step, and, as it is now, I wouldn’t have any reason to believe that if I did follow every step, that I would end up with working code. I wouldn’t know that what I’m doing along the way is implementing a “complete trade flow”, because the doc never told me that’s what I’m going to do. I would look at that doc as something more like a collection of useful reference notes about how to do different things, but it wouldn’t be obvious to me that it’s a joined-up, step-by-step focused experience.\r\n\u003e When I say simplest possible bot, I mean like _the simplest possible bot_:\r\n\u003e e.g. a bot that listens for all incoming offers and prints out offers to sell BTC at less than a given distance from market price.\r\n\u003e DEAD simple.\r\n\u003e If I have to set up regtest, deal with arbitration, mess with docker, etc, I’m going to walk away\r\n\u003e unless I’m super motivated.\r\n\u003e If I follow a guide that ends up in me writing a super simple bot, and the whole thing takes me ~15 minutes,\r\n\u003e I’m going to be effing thrilled\r\n\u003e and hungry for more\r\n\u003e I’ll be happy to take on more ambitious stuff,\r\n\u003e because I have a base to build on\r\n\u003e and a metal model of the project that I like\r\n\u003e \r\n\u003e bernard [2:08 PM]\r\n\u003e Ok, I'll create several tiny docs that allow user do to something on mainnet, so that they could do it out of the box\r\n\u003e \r\n\u003e cbeams [2:08 PM]\r\n\u003e and basically a positive emotional experience.\r\n\u003e sure, one is enough to start with.\r\n\u003e in my experience, these are deceptively difficult for people to write the first time around\r\n\u003e making things simple is never easy\r\n\u003e so I’d nail one down\r\n\u003e and then move on to the next\r\n\u003e don’t try to do several at once.\r\n\u003e By the way, I’ll happily be the guinea pig to walk through that first doc. I’d really love to write my own trading bot for Bisq!\r\n\u003e For this to really work, it’ll mean that I need to build your #bisq-desktop fork from source, because that’s the only one that will have the `--httpApiEnabled` flag available. This is fine, and you should definitely write the doc that way, i.e. with literally whatever steps are necessary to build a functional trading bot. When everything is ready for primetime and we integrate the http api into the canonical bisq-network/bisq-desktop repository, that step in the doc will go away, or get a lot simpler, of course. But in the meantime, if it actually spells out working instructions, that means that anyone can use the doc as soon as it’s written. We can start getting feedback on this stuff even before officially integrating it, which would be excellent.\r\n\u003e \r\n\u003e bernard [2:16 PM]\r\n\u003e Thank you for quick feedback Chris. I'll try to get it written ASAP\r\n\u003e \r\n\u003e cbeams [2:16 PM]\r\n\u003e Killer. Thank you.\r\n\u003e \r\n\u003e bernard [2:18 PM]\r\n\u003e Yes, that was another part that was making the writing hard. I want sure how the instructions should be cause I was writing it with integration in mind. I'll write it against current bisq-api code\r\n\u003e \r\n\u003e cbeams [2:19 PM]\r\n\u003e Yeah, just write it according to whatever I literally must do right now to get up and running. Then the doc should get simpler over time as more stuff gets integrated, etc.\r\n\u003e Feel free, by the way to fully steal the format from the Spring and Gradle guides.\r\n\u003e They are nearly identical in structure for a reason :slightly_smiling_face:\r\n"}],"action":{"name":"View Pull Request","url":"https://github.com/bisq-network/bisq-docs/pull/54#issuecomment-389822839"}}}</script>
<script type="application/ld+json">{"@type":"MessageCard","@context":"http://schema.org/extensions","hideOriginalBody":"false","originator":"37567f93-e2a7-4e2a-ad37-a9160fc62647","title":"Re: [bisq-network/bisq-docs] Produce the simplest-possible getting started guide for the Bisq HTTP API (#54)","sections":[{"text":"","activityTitle":"**Chris Beams**","activityImage":"https://avatars0.githubusercontent.com/u/301810?s=160\u0026v=4","activitySubtitle":"@cbeams","facts":[]}],"potentialAction":[{"name":"Add a comment","@type":"ActionCard","inputs":[{"isMultiLine":true,"@type":"TextInput","id":"IssueComment","isRequired":false}],"actions":[{"name":"Comment","@type":"HttpPOST","target":"https://api.github.com","body":"{\"commandName\":\"IssueComment\",\"repositoryFullName\":\"bisq-network/bisq-docs\",\"issueId\":54,\"IssueComment\":\"{{IssueComment.value}}\"}"}]},{"name":"Close pull request","@type":"HttpPOST","target":"https://api.github.com","body":"{\"commandName\":\"PullRequestClose\",\"repositoryFullName\":\"bisq-network/bisq-docs\",\"pullRequestId\":54}"},{"targets":[{"os":"default","uri":"https://github.com/bisq-network/bisq-docs/pull/54#issuecomment-389822839"}],"@type":"OpenUri","name":"View on GitHub"},{"name":"Unsubscribe","@type":"HttpPOST","target":"https://api.github.com","body":"{\"commandName\":\"MuteNotification\",\"threadId\":336252617}"}],"themeColor":"26292E"}</script>