Writing a Bot Framework Book in the Open (Oh, my)

I've toyed with writing technical books in the past. In fact, I have an XML book that I've been slowly building out over time. Maybe one day I'll actually finish it. Writing a book is a difficult process even when you know all the material. Motivation and time is always a factor. You might be able to work through 1-2 pages a day, but if the book is 300 pages long, it could take you half a year to a year to finish the first draft. That's not a great pace.

With all the work that I've been doing with Microsoft's Bot Framework, I've had the feeling for a while that it is culminating to something. What that is, I don't know, but I decided a few months back to start writing it all down (well… typing it).

Most of the stuff out there right now is for the .NET SDK, and I've been working almost exclusively with the Node.JS SDK. What's more, I've been doing all of it in TypeScript, so I thought that I should start documenting what I've been doing. I've actually had a few pull requests accepted with the official Bot Framework documentation, so I must know something.

Furthermore, in doing the video tutorials, I've been putting together a timeline of progress moving from simpler tasks to more complex and complete tasks. This has afforded me a sequential look at programming with the Bot Framework that would work well for a book.

I wasn't sure exactly how I wanted to accomplish this though. I'm less concerned about "getting published," and more concerned with getting some good documentation out there, and helping others. Amazon's ISBN distribution has pretty much made on-demand, self-publishing such a simple route that, honestly, I probably was never going to push this out to a regular publisher. I could still seek out a full time publisher, but I can do it on own terms, and if all else fails, I can do it myself. Truth is, for a technical book, it's better to invest in a high quality copy editor and a technical reviewer than anything else. Distribution for a technical book is always going to be online, whether through Amazon, or promoted on social media or in newsletters.

What are these terms? I want the book to be freely available. The point is to inform people, not to make money. It's a matter of convenience. If you just want to learn, you can learn online. If you want an eBook or PDF copy, you can grab one. If you want a print copy, you can purchase one.

If I'm not going to be a best-selling millionaire (like all technical books writers are), then does it make sense to keep the progress of the book secret? Not really. The other thing holding me back is the potential for embarrassment if the work sucks… and I'm pretty sure it does right now because I've yet to expand it, refine, or even proofread it.

My process for writing is pretty simple. The first thing I do is come up with an outline. I then go through the outline, writing chapter after chapter, based solely on the information in my head. The rough draft of the book is really a fleshed out outline that gives me a good look at where the book is headed. Some chapters are long. Some chapters are really short. I then go back through it a second time. Only this time, I add some research to the mix, and try to finalize each chapter in regards to the information it'll contain. I then do another pass at the book, proofreading, changing, and filling in any missing details. Afterwards, this would be the point that I would pass the book to a copy-editor and a technical reviewer, incorporating their suggestions and changes before going over the book a final time.

A lot of work right? That's partially why I like the idea of writing the book in the open. It'll keep me motivated; otherwise, the book will languish as an incomplete, poorly written mess.

Where am I at in the process? Still writing chapters for the first time, so I haven't yet worked in any research or accomplished any proofreading. I have, however, dumped it on GitBook. I imported my Word document, so there were a lot of formatting issues I had to work out. I also integrated GitHub, so that the files are stored on there. My plan is to progress much faster than I have been, and the first thing I need to do is catch up to the information in the tutorial videos that I've been recording. The tutorials themselves act as nicely segmented chapters, so the book and the tutorial series will be reflections of one another.

In any event, the book/files are up there for anyone to start looking at, and I'm more than willing to accept advice or ideas. You can comment directly in the GitBook interface. It's still very early, so many of the issues will clear up once I make the second round through the book, but there is no harm in commenting early.

Once the book is finished, I can then decide how I want to distribute it: web-only, eBook, print, etc. No matter what, though, it will definitely remain available for free online.