Having a technical book on the shelves can make anyone anxious. Technical authors publish entire books that depend on open-source software, free APIs, and constantly changing data. In some ways, supporting a technical book is like maintaining a popular GitHub repository. When users find bugs, I attempt to address and remedy them. In some other ways, it is much harder. If I want to patch a significant bug, I can’t exactly walk into every Barnes & Noble and pencil it in.
I have taken a lot of steps to make these books functional on release and easy to support down the line. Some have been very effective, and others have not. I will list them below and discuss how lessons from Automated Trading with R informed my decisions on how to best support The Blender Python API.
The Game Plan
Below we discuss the many steps technical authors can take to support their books, the steps I have taken, and my experience with them.
Host Important Code and Data on a Static Fileserver
This is one of the most effective things I have done to enhance the consistency and support-ability of Automated Trading with R. Before I began writing, I pointed trading.chrisconlan.com to an Amazon S3 bucket and made a commitment to store static data files in it. I only ended up storing two files there, which were original data sets on S&P stocks and their addition dates. Nonetheless, I was able to put things like this:
SPDates <- read.csv("http://trading.chrisconlan.com/SPDates.csv",
header = FALSE, stringsAsFactors = FALSE)
directly in the book. This allows me to sidestep any conversation about data format and data parsing in favor of the core topic. Additionally, I can update the underlying data whenever I like without breaking my reader’s code.
In The Blender Python API, we deal with same problem of data dependencies, but we also deal with software dependencies. Most notably is a file called ut.py that contains some of most advanced algorithms we develop in that text. In order to build on these lessons and algorithms without reprinting the code, I occasionally pause the reader and request the he download the version of ut.py that corresponds with that point in the text. With the code in an S3 bucket, I simply say “visit blender.chrisconlan.com/ut.py” and the user sees the Python code pop up right in their browser.
Recommendation: I will do this for every book I publish. It is quick and easy for those with the requisite networking skills and has no cost or downside.
Set Up a Community GitHub Repository
For some background: Your publisher will typically set up an official repository for your book. The code in the official repo will correspond exactly to the code in the book, so this will not be updated unless you update the book itself. This is important to have.
With Automated Trading with R, I set up a community for readers to build out together. This began as the same repo as the official one, then evolved into the community repo as we changed it. In reality, the community repo was not frequently updated, and updates were usually confined to commenting on compatibility and readability issues. This is partially because there have not been any actual bugs found since release, and partially because I did not properly encourage community involvement.
A major advantage to having this repo open is my ability to use GitHub Issues to answer questions. Programmers are comfortable and familiar with this tool, so I would keep a community repo open if only to manage these requests.
Recommendation: I will likely do this again for the GitHub Issues portion. My new book may not be appropriate for community building, though. If your publisher’s official repo gets sufficient traffic, you may want to rely solely on that.
Set Up a Community Forum
I set up r.chrisconlan.com for users to discuss the book. This has been helpful in many cases, but mostly serves the same function as GitHub Issues, and has been harder to maintain. Given all the avenues readers have to get in contact with me, this one has ended up being the least effective. I would rather consolidate all public support requests to GitHub Issues.
This forum was also meant to discuss joint development of the software and new ideas, but it has not been successful in doing so. It may just be that traders do not want to share their secrets, which is perfectly understandable. I felt that Automated Trading with R lent itself to community development, so I needed an avenue for readers to share constructive ideas. If a given book focuses purely on education rather than community development, I think a forum would be entirely unneeded. This is certainly the case with The Blender Python API.
Recommendation: I will not launch a forum for The Blender Python API. If I release a book in the future that is conducive to community development, I may accomplish this through a forum. In general, forums need a lot of love to become self-sufficient, so it may not be appropriate for every author.
Give Readers a Way to Get in Touch
The best way for readers to get in touch with my is through a GitHub Issues feed associated with a book, or the contact page on this website. I have had a lot of productive discussions with readers going through relatively banal dependency resolution (e.g. an old version of X doesn’t run the code on Y operating system) and readers debugging complex programming logic. I am usually available to send a quick not about this and get it solved. In return, I get more in touch with the software ecosystem of my readership, and I am better-equipped to answer such questions in the future. A few times, I have learned that my code works but does not drive home the lesson of the chapter. In these cases, I have announced teach-ability updates and clarifications on r.chrisconlan.com.
Recommendation: Absolutely give readers a way to get in touch.
Be Crystal Clear about Software Versions
This is an easy one. Everyone has a different computer with different software. Most of your readers have already downloaded and familiarized themselves with a different version of the software used in your book. So, be clear at every step what version of what software you are using to arrive at your result. This will squash a lot cross-compatibility bugs before they even occur.
Recommendation: This is more of a best practice than anything. I state it here because it is often ignored.
Use Technical Reviewers with Varying Skill Level
Implicit to this recommendation: Have at least two technical reviewers. This has been instrumental in ensuring my code is bug-free and legible for a wide audience. While an experienced programmer may discover advanced technical issues, he is also more likely to ignore minor technical issues that can trip up a beginner. A beginner programmer is more likely to encounter run-time errors from minor bugs or lack of explanation, but is also more likely to accept advanced errors that do not cause run-time errors. I rely on advanced programmers to ensure scientific validity, and I rely on beginner programmers to critique the reader experience.
There could not be a more perfect harmony here. I highly recommend this approach to technical reviews. It is especially important to point out here, because most authorship protocol I have encountered only require a single reviewer. This single reviewer is almost always an advanced programmer, which leaves the reader experience ignored and without criticism.
Recommendation: This is a must have in the writing process.
Get in Touch
Authors and readers, let me know what you find helpful or cumbersome. Feel free to comment below or contact me.
Leave a Reply