[bisq-network/bisq-docs] Produce the simplest-possible getting started guide for the Bisq HTTP API (#54)

Thu May 17 10:36:26 UTC 2018

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:

> bernard [12:53 PM]
> @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 ?
> 
> cbeams [1:39 PM]
> 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”.
> 
> Getting Started Guides are about providing step by step instructions to accomplish a specific use case that results in working code.
> 
> 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/.
> 
> We followed the same approach at Gradle, and again you can browse the available Getting Started guides at https://gradle.org/guides/.
> 
> Have a look in particular at https://guides.gradle.org/building-java-libraries/
> 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).
> 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
> 
> 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.
> 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,
> 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.
> 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.
> Along the way, there’s plenty of room for sidebars that provide context and color,
> 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.
> the idea with these guides is that you write a lot of them.
> Notice how there are very many of them in both the Gradle and Spring cases
> 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.
> 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.
> From there, the user will be hungry to come back for more,
> they’ll be ready to consume more general purpose, reference-style documentation,
> because they’ll have had a pleasant, guided, and ultimately successful experience getting everything set up for the first time.
> 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.
> 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.
> I started things off with the deeper directory structure you’re following suit with,
> but as things have progressed, I’ve decided to keep everything flat, at least for now,
> and to organize and group things “virtually” via the `index.adoc` file
> I have a much larger outline / ToC for the docs site on its way,
> but ultimately, we don’t know what directory structure (if any) is going to make sense in the end,
> so I just want to keep everything flat.
> Basically think of the whole site like a wiki that is evolving toward becoming a comprehensive Bisq Network operator’s manual.
> And like (most) wikis, it has a flat namespace.
> Allows for maximum flexibility in the future with structuring things,
> and minimizes the need to do a lot of relative pathing when linking to other files.
> 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?”
> 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.
> 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.
> 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.
> I think it’s reasonable to assume that a fairly large number of users would want to write a trading bot though,
> indeed that’s the whole thing that got this effort going in the first place.
> 
> bernard [2:02 PM]
> What I've described is complete trade flow which is a complete use case for Bisq I guess
> 
> cbeams [2:02 PM]
> so what is the simplest possible trading bot? what language should it be written in to be a most effective demonstration? Java, Python?
> there are tons of such decisions to make,
> 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.
> 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.
> When I say simplest possible bot, I mean like _the simplest possible bot_:
> 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.
> DEAD simple.
> If I have to set up regtest, deal with arbitration, mess with docker, etc, I’m going to walk away
> unless I’m super motivated.
> If I follow a guide that ends up in me writing a super simple bot, and the whole thing takes me ~15 minutes,
> I’m going to be effing thrilled
> and hungry for more
> I’ll be happy to take on more ambitious stuff,
> because I have a base to build on
> and a metal model of the project that I like
> 
> bernard [2:08 PM]
> 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
> 
> cbeams [2:08 PM]
> and basically a positive emotional experience.
> sure, one is enough to start with.
> in my experience, these are deceptively difficult for people to write the first time around
> making things simple is never easy
> so I’d nail one down
> and then move on to the next
> don’t try to do several at once.
> 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!
> 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.
> 
> bernard [2:16 PM]
> Thank you for quick feedback Chris. I'll try to get it written ASAP
> 
> cbeams [2:16 PM]
> Killer. Thank you.
> 
> bernard [2:18 PM]
> 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
> 
> cbeams [2:19 PM]
> 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.
> Feel free, by the way to fully steal the format from the Spring and Gradle guides.
> They are nearly identical in structure for a reason :slightly_smiling_face:

-- 
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/54#issuecomment-389822839
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.bisq.network/pipermail/bisq-github/attachments/20180517/422e9618/attachment-0002.html>