How Software Craftsmanship Made Me a Better Author

When after fifteen years as a software developer I decided to try my hand at writing fiction, I was prepared to start at ground zero. Apart from a few attempts at fiction in high school, the only substantial things I’d written were software architecture and requirements documents. I wasn’t an English major and had never taken a creative writing course. Somewhere inside me, however, was a story that had to get out, so one day I stopped dreaming about the darn thing and started typing.

The journey from there to where I am now, with one published book and two more waiting for edits, is a story in itself, but what surprised me were how many of the skills I’d learned as a software craftsman that helped transform the vague characters and ideas in my head to a polished, publishable novel.

Writing a good book, I discovered, was a lot like writing good software. Here’s why.

Design

Design is the first step in software development after you know what it is you want to build, aka the requirements. It involves sitting down, usually with a group of other developers, and creating a high-level plan of how you’re going to turn this collection of ideas into working software. They key words here are “high-level”. At this point, the developers don’t know what the code will look like. They can’t tell you which fields will be on what screens, nor the precise database model, but based on what the application needs to do, they can tell you the language it needs to be written in, whether it will require a distributed architecture such as microservices, and what other technologies will be required. Design requires a lot of thought and is important because wrong decisions can be costly later on or result in sub-optimal software.

The same applies to starting a novel. Authors usually begin with only a rough vision or flashes of a story, perhaps an intriguing character or setting. Before they begin writing, they normally create a brief outline of the major events and conflicts. The outline often follows an established story structure, such as the Hero’s Journey. Other high-level items are tense and perspective, each of which are critical decisions that can significantly affect the impact the story has on the reader, and as with software design, choosing poorly may require a complete re-write later on.

Creating a structured outline was a natural step for me, and throughout the process, it was instrumental in keeping my momentum because I always knew what I was aiming for.

User Stories

Many outside of the trade don’t know that software developers write stories, too, especially those who practice agile. User stories are small, digestible units of business value, such as allowing a user to log in to the application or adding a new section to a web page. They’re a few sentences long and contain at a minimum three pieces of information: who is it for, what needs to be done, and why is it important. By themselves they don’t make a complete software package, but when strung together, these independent units become a feature, and those features work together to create valuable software.

If you’ve ever used index cards to plan your story, this should sound familiar. Like user stories, the index cards represent digestible portions of your novel. While each card could stand on its own, it’s not until they're strung together that they make a complete, enjoyable story. Scenes have a “who” (whose perspective is it from?), a “what” (what happens?), and a “why” (how does it move your story forward?). When put together, those scenes create something greater than the sum of its parts.

I used virtual index cards extensively in my first novel and continue to use it today. I love the ability to drag-and-drop them around, or move them in and out of the reject folder as the story evolves. I also attach metadata, such as whose POV the scene is from and the story date, which I refer to often as the novel progresses.

Structure and Coding Conventions

Good software has structure. It’s the roadmap developers use to navigate complex code. Without it, adding features can be like trying to find the one document you need in a giant, unsorted pile of papers. Code should be intuitive to locate by its responsibility, cleanly formatted, and use naming conventions that leave little doubt about its function and use. Curly braces, for example, should be consistent for readability, regardless if you choose to put them on a newline or inline JavaScript-style. Doing so can shave hours or days from a software project, especially when onboarding new developers. Any developer who’s tackled a codebase that didn’t adhere to the above was probably ready to tear their eyes out before their first week was done.

So too with a novel. The author’s “voice” is their style. It sets a tone and structure the reader quickly adapts to and comes to expect, not just from this book, but anything on the shelf with your name attached. If they like your style, they’re more apt to buy your next book. If your style is inconsistent, readers become annoyed and will seek another less jarring source of entertainment.

It wasn’t until after my second book that I recognized my style, but once I did, I applied the same principles to it that I do my code and refactored my first book to make it consistent, so readers who pick up any book in the series will know what to expect.

Syntax

If you’ve ever seen a squiggly line in Word telling you that you’ve misspelled something or used the wrong tense, you know what syntax is. In programming, a wrong word usually means your program will error. Integrated Development Environments, or IDEs, even use the same squiggly lines to tell developers when they’ve typed something that will probably break. Each programming language has different syntax, and while programs can probably be cobbled together without knowing the syntax well, creating well-crafted software that other developers can contribute to requires mastery of the syntax.

As an American writer, my syntax is the English language. Before I sat down to write my first book, I set time aside to re-learn everything I’d slept through in my English classes. Tenses, punctuation, sentence structure… I brushed up on everything before I sat down to write, and when I learned something new, I would go back and apply it to everything I’d already written to reinforce my learning. While incorrect syntax won’t cause a book to throw an exception, it annoys readers and is definitely worth the investment to master.

Refactoring

Code refactoring is the process of restructuring existing computer code—changing the factoring—without changing its external behavior (thanks Wikipedia). Developers do this for a variety of reasons, including deduplication and dependency management, with the ultimate goal of making the code clean, maintainable, and hopefully a joy to work on. It’s a constant process on most active projects, and those where it isn’t are doomed to code-spaghetti hell or, at the very least, a complete rewrite because the software becomes unmaintainable.

Maintaining a novel is the same. Stories evolve organically as we write. We’ll get half-way through the book and realize that a character or plot item earlier on needs to change to fit this great idea we have. Changing that, however, may have rippling effects in the next chapter, or many chapters. While we could ignore it, doing so creates a mess in our story. Correcting it requires fearless refactoring to ensure our story flows as smoothly as it did before.

In the beta stage of my first book, I ran into a major problem: No one cared about the protagonist. Fixing this required establishing better motivations, giving her a more complex background and challenges—and fearlessly refactoring every single chapter to account for this new, stronger, and (hopefully) more interesting character. The process was similar to major code refactors throughout my career, and like those, it was totally worth the effort.

Iterations

In agile development, software is delivered in iterations, or incremental value. You don’t wait for the entire application completed before showing it to stakeholders. This can save months or years of re-work because you’re getting constant feedback from the people who are going to use the software about whether you’re building the thing they need, then making course adjustments along the way.

My first book was in its third draft before anyone even knew I was writing one. It’s no surprise that it had some major problems, like a protagonist no one cared about, which required a complete revision to salvage. For my second book, I took a page from agile software development and delivered each chapter to my alpha reader as soon as they were finished. Her quick feedback allowed me to fix major plot and character issues before they went any further, costing a chapter or two of edits at most, and saving me from another lengthy revision. I did the same with my third book, and you can bet I’ll do the same with my next series.

Quality Assurance

There’s a rule in many shops that developers should never test their own code because they’re too close to it. They subconsciously know what will and won’t work, and stay away from things an end user would happily blunder into. QA’s job is to be the user. They make sure the developer’s software works by testing the crap out of it, and if they don’t like something, the software won’t see the light of day until the developer fixes it.

Did someone say “editor”? Absolutely. As authors, we do our best to use good grammar, spelling, keep our plots tight, and our characters consistent. But let’s face it… these manuscripts are our babies. Without an editor to review our manuscripts with a professional eye and a reader’s interest, what we would release into the world probably wouldn’t be ready for prime time. Alpha and beta readers also help, though usually not as much as an editor.

Acceptance

The ultimate judge of whether software is ready to ship is the customer. The last step before launch is getting it in the customer’s hands to make sure it does what they need.

To me, acceptance of my book is reader reviews. Professional bloggers, people I don’t know rating my work. If the reviews are generally positive, I’ve done my job as an author, and the more of that feedback I can get prior to release, the better my book will be.

Delivery

Software is only useful if it makes it into the hands of the users, even if that user is only the author themselves. That means finishing it. Now, "finished" could be sooner than expected (rare), or require more stories than originally planned because, once in the hands of an actual user, requirement gaps become achingly obvious. Sometimes the software transforms in ways the designer never envisioned, other times not so much.

Either way, it always starts as something small, fragmented, and unrecognizable from the finished product. The only way to realize its full beauty is to see the process through to the end. If the agile process is done right, the results are rarely disappointing.

Stories are the same. They're slow, painful things to start that have little shape or direction. If I let that dictate my writing process, I would never finish everything. But I've learned that as long as I follow my writing process, almost every story I begin can and will become something beautiful. Therefore, after over a decade of writing, my number of finished stories outweighs my unfinished stories 10 to 1.

Marketing and Discovery

It’s all well and good to build a fantastic app and post it to an app store. It’s another thing entirely to let people know it’s there. iTunes has hundreds of thousands of app submissions a year, most of which you’ll never hear about. Being successful means marketing—letting users know your application exists, that it’s cool, and that they can’t live without it. The game industry has a formula for doing this, which includes building hype up to release, establishing a platform, and launching with advertisements and grand flair.

My first book launched on Kindle with little fair and, you won’t be surprised to learn, had only a few sales, and I knew all the buyers by name. Since then I’ve begun to put more effort into building a platform—a website, twitter account, a blog with actual posts in it—with the hopes of creating something others are interested in following. If I don’t, I have no illusions that my second book’s fate will be the same as my first’s. As authors, we need a marketing platform so readers know our books are out there. That means getting followers, subscribers, posting in forums, building some excitement about this cool thing you’re going to release into the world, because if you don’t, your book will be lost in the hundreds of thousands of others that will be published this year.

Patches

Few applications in history have ever launched without bugs—none that I’m aware of, in fact. As soon as it’s released into the wild, someone will do something you weren’t expecting that will cause a catastrophic failure and likely lead to bad ratings, which will hurt sales if you don’t fix it quickly.

I’ve lost track of the number of edits I’ve done on my first book, yet every time I read it, I find something I missed. Each fix doesn’t merit a new push to Amazon, but if they’re severe enough, it’s worth pushing a new revision so readers don’t feel like they’ve been duped into buying a flawed product. Some readers are vocal about the flaws they find and post it in their reviews. Don’t give them reason. No manuscript is perfect, but that doesn’t mean we shouldn’t try within reason.

Conclusion

You certainly don’t have to be a software developer to write a novel, but for those who are, heed your programmer instincts. In most cases, they won’t steer you wrong.

Updated 22-May-2023 to add the "Delivery" insights.