Getting Started with Writing a Technical ebook

The early release of my ebook Juggling JSON with jq comes out tomorrow! However this post is more about the process of writing the book itself.

Getting started on an technical ebook, (such as Juggling JSON with jq), requires a bit of upfront setup. On the ebook side, I decided to go the route of writing the book in Markdown, and generating the various formats using Sphinx. While I feel most comfortable using Markdown, and yet Sphinx uses reStructedText by default. So I had to coax Sphinx to accept Markdown by using a project called m2r. Generating the PDF version of the ebook took a bit to get working. Sphinx uses LaTeX to generate PDFs, and LaTeX while powerful can be clunky to work with. I wrapped everything up with an invoke script, and now I can quickly generating new versions of ebook in the various formats I want to support.

Something unique to writing technical books, is the need to have actual working examples. You can learn by reading, but working through exercises and examples re-enforces that learning. In the case of Unjumbling JSON with jq, I needed an example REST API that readers play with. I searched for some nice open APIs, but nothing seemed very compelling. Many of the open APIs require some form of user registration and non-trivial authentication method that would complicate the examples in the book. So I setup a simple demo API for the book. Thankfully with Docker and Flask, that isn’t a particularly daunting task. (Dockerizing most of my webapps definitely made my live easier overall.)

Finally using Gumroad made marketing and selling the book a lot more approachable. Getting everything setup for e-commerce is a daunting job, if you plan on doing it yourself. Thankfully for ebooks, and similar digital products, Gumroad solves most of the problems one can encounter. I definitely recommend using them if you are planning to do something similar.

Perfection in Your Process

I have a serious character flaw. I’m a perfectionist. Nothing kills creativity like trying to get everything right the first time around. One of the most important skills I learned in professional writing: is create first, edit to perfection later. Give yourself leeway and freedom to make mistakes and to experiment.

There is a second part to the lesson though. You must treat and follow your process as closely one should practise religion. In writing, a process gives you the structure to write faster, better and with more freedom. In programming and developing applications, rigour in sticking with your process is essential for the project’s health and your sanity.

Processes like planning, documenting, testing, deploying and fixing bugs should be well worked out in the developer’s mind. Being drilled, the developer can control her environment better. In a controlled environment, there are no surprises or unexpected issues. Everything works with the precision, logic and accuracy of a Swiss watch. With a well documented and followed process, you can measure efficiency and progress.

In a controlled process, you can work out what you can expect to happen and how. Your developers can gauge how their work is progressing. Your designers can see how well the implementation follows the design. Your testers know where to spend time testing. And your business people, can figure out the cost in time, people and materials your project will take. Everyone know what is expected of them. Your team feels less stress, and works more effectively. That is why ideas like Sigma Six and best engineering practises exist. Japanese manufacturer stressed over their processes bring them to perfection. No wonder why Japanese manufacturers can corner the market.

Without a process, chaos ensues, stress builds and projects fail. So if you manage a team or a project, do your team a favour: figure out a process that works for everyone and stick to it. Your team will appreciate less stress and chaos. And your bosses will appreciate a project well done. Perfection belongs in your processes.

Task Oriented Architecture

As neotechnophiliac (a.k.a. person crazy enough to run alpha releases of software), I love to experiment with different technology. And these tests are often for the pursuit of pointless knowledge and killing time. Technology and engineering are a lifestyle for me.

Most people don’t see technology that way. Technology comes in two flavours: toys and tools. Developing a tool is a challenge of engineering. However users don’t care about tools. (How many people care about carpentry tools?) Users want tasks done. The challenge of usability design is to create task-oriented user interfaces.

Simplicity is important in UIs. The Palm OS (IMHO) designers created one of the best UIs out there. Practically everyone (except Microsoft) in the smartphone, handheld and ultraportable market copied their design. The Zen of Palm, as a primary “pamphlet” for Palm programmers, emphasizes the importance of using a simple UI for getting a particular task done. Compare that with the desktop world, with applications looking like something out of configuration and accessibility hell. The cockpit of a jetliner often looks less daunting than a desktop office suite.

Efficient and reusable workflow helps users greatly getting their work done. A UI that lets you perform a task with 3 interactions works better than one with 5. Burning a CD under Nero, requires you either to click-through 8 screens on a wizard or navigate a massively clustered UI. Under K3B it takes a drap and drop, clicking the “Burn” button, throwing in a CD and you’re done. Neither you have to crawl through a wizard ever time. Nor do you have to deal with a clustered, non-trivial UI.

Remarkably, the most usable UI I’ve worked with, originated in the software libre world. Thats because the end-users of the programs, built those programs. Also open source, allows people to “fork” software. Forking let you take a software libre application that doesn’t meet your requirements, and built something that does from the same code base. In such an environment, software components such as UIs evolve much faster than in the proprietary world.

With my own life, I prefer using open source applications because they give me more freedom, and hence work better for me. Its amazing how much simpler, streamlined and usable most free software is. And it only gets better. I like my KDE 3 applications, but the KDE 4 applications once stablized will work even better for me. Thats because usability designers such as Celeste Lyn Paul work with the KDE developers on making better task-oriented UIs. A big thank you to all the KDE 4 developers, designers and contributers.