Tips for Technologists #13: Writing Software is like Writing a Book

In Tech Digest by Nick Ruffilo

Great software — like great writing — has many chapters and sometimes multiple authors; it goes through many revisions before taking final form.

By Nick Ruffilo

Coding, like Writing, is an Art

If you can spell and understand the rules of grammar, you can write. If you can type and know the keywords/grammar of a programming language, you can code. The only difference is that in writing, you can get away with bending a few rules of grammar, coding is a bit more strict. Along the same lines, just because you can write a few lines of code doesn’t mean you are good at it. It takes practice. Also, as in writing, some people have a natural gift for writing engaging (good) code, and others have to work harder at it.

Coding Can Be Compartmentalized

If coding is like writing, how come there isn’t just one programmer per project? Well, there can be, and for smaller projects, there often is. But, for large projects, that wouldn’t be feasible. If you think of pieces of a software like chapters in a book, I can easily explain how it gets chunked and divided to multiple programmers.

Lets take “Beauty and the Beast” as our example story. Clearly it has a beginning — small-town girl, beastly prince — and a clear ending — Prince’s spell is broken, everyone lives happily ever after. Well written software requirements are exactly the same. It will clearly state to the programmers what you are starting with, and what you want to end with. If this is missing or unclear, you’ll be putting yourself at risk for the software to do unintended things.

The software engineer then has to storyboard the application, to figure out how we’re going to go from small-town girl and cursed prince to happily ever after. Each logical step (think of these as chapters) has a beginning (input) and end (output). Each step, or chapter, can be handed out to an individual programmer. While all the pieces before may not have been written, there is an assumption that when the story or app is done, my piece will get X as an input, and my code will turn it into Y, which the next programmer will use for their piece.

Edit, Edit, Edit

Can you imagine if you simply took the first manuscript that an author gave and published that? You get the same results if you simply take the first cut of an application. A good developer will test their software, but it is always good to have a second pair of eyes examine both the code as well as test the inputs/outputs. In software, your QA (quality assurance) team is akin to your editors. They look at the manuscript, find plot holes, find issues, and return that list to the programmers to fix. As with editing, this isn’t a one-time process. Depending on the length and complexity of the application, you can have a large number of Dev->QA->Dev loops. Quality code may take longer to write and test, but it saves time/money on bug fixes, and runs faster and makes for a better user experience.

There’s More Than One Way to Do Things

If you have a story, and your main character needs to acquire a hat, there are a large number of possibilities. They could buy the hat at a store, the hat could be on sale, they could order it online, get it from a street vendor, receive it as a gift, find it in their attic, take it from their hat rack, find it mysteriously on their doorstep, etc. Some ways are easy, some ways are hard. If your character is in the desert, ordering the hat online isn’t an option. If in the desert, and it magically appears, you need some way to justify that, or your story will be unbelievable. Code is the same way. Different situations create different limitations on what can be done. Also, there are usually many ways to get something done — some are quick, and some are not. This is important to keep in mind when developers are requesting a long time to do something that seems simple. Instead of asking “why will this take so long?” a better question is “what are the issues that are preventing this from being a simple task, and what are the ways this can be done?”

How This Helps Coders

To my coding audience, I realize this has largely been focused on the business side. The important lesson here is to recognize that you are essentially telling a story. By using comments and pseudocode, make sure you outline your story first. Think of multiple ways to do things, and don’t hesitate to change the way you were going to do something when you find out that your initial logic may not be the best solution.

About the Author

Nick Ruffilo

Nick Ruffilo is currently the CIO/CTO of He was previously Product Manager at Vook and CTO of BookSwim.