August 27, 2020 // By Larry Smithmier
I recently told a colleague that “writing a 1000+ word article wasn’t hard, getting started was hard” and that he should “write about what he knows, or what he wants to learn about”. So now I want to apply this strategy to the process of writing a technical blog post. Writing a blog post is very similar to writing an essay. Though it has been years since my formal education as a student in college English Composition classes, a quick Bing search about essay construction gives me the refresher I need. I start with an introduction (this paragraph), follow it with my selected main points (for me that is what you know and what you want to learn), and end with a conclusion.
Writing about something you know helps solidify your knowledge by forcing you to express it in a form that is accessible by an audience other than your peers. The ability to provide an understandable context of how and why programmers approach problems has value. The more the customers for our software know about what goes into creating it, the better their ability is to provide meaningful feedback. Writing about how and why you approach problems the way that you do forces you to examine your process so that you can replicate the successes and mitigate the failures.
Another reason to write about something you know is to provide insights that you have gained through the variety of work that you have done for different clients for whom you have worked. When siting down to write about software architecture, you are not writing it for others at your current or past projects. You are writing for those about to start similar projects. You are writing about the lessons learned the hard way so that your peers can avoid making the same mistakes. Software development is both an art and a science, and within either discipline there are forums for publishing successes and failures. Honesty about what didn’t work has much greater value than simply promoting yourself by only reporting what succeeded.
Writing a short form article about something that you want to learn helps by forcing you to start with a SMART (Specific, Measurable, Attainable, Realistic, Time-bound) goal. Unless you are planning on writing a book, the learning goal for an article needs to be specific and limited in scope. Writing an article on how to use a new language feature to implement a solution to an existing problem is a topic that can be covered in a 1000-word blog post. Another example of a properly contained topic would be comparing the performance of various popular solutions to a simple problem.
Even though you define a goal/problem in your introduction, you shouldn’t measure your success solely by how close you come to solving it. Another measure of your success is the existence of a new article. At the completion of the article, you have either achieved your desired result or you have documented a method that does not work. This success, even without your solution, is and should be a great motivator to continue to write more articles.
You are a consultant or a developer. Your successes are in contrast with that of a college professor. Your research needs to focus on attainable goals: how to solve a new problem with a familiar technology or solving a familiar problem utilizing a new technology. Instructors, college professors, and other researchers are charged with pushing the boundaries of human knowledge. As a problem solver, consultant, or developer, you should be focused on expanding your own boundaries.
It is unrealistic for anyone to define the whole breadth and depth of a subject within 1000 words. A short form article constrains you to focus on either a shallow depth and limited breadth or a deep dive into a specific portion. A good example of limiting the breadth and depth of a subject would be a survey of the different networking options available when setting up a Kubernetes cluster. In contrast, determining the effect of different BatchFlushIntervals in WindowsAzure.ServiceBus implementations on the throughput of a particular workload would be good a deep dive article topic.
Limit yourself to one week when writing on a subject about which you want to learn. This is long enough for you to do a few hour-long experimentation sessions and then replicate them. If you work for a company that has an active developer community and you have not made any progress by day two, ask for some guidance or a push in the right direction. If you don’t have options available to you at work then explore other networking options, such as a local user’s group or a similar community on one of the tech forums (StackOverflow or Reddit are great places to start). Any topic that takes you longer than a week to research is something that you should probably invest in a course or book to learn. Adjust your time limit as you write more and more articles, because your optimal time might be different than mine.
Finally, writing about a less familiar subject also helps anchor the material in your mind. Having to put the concepts into your own words in a way that will allow someone else to replicate your experience forces you to slow down and think about each step of the process. When writing a learning article, think about building a VM with a vanilla OS to force yourself to consider each tool and step you take along the way. You can use snapshots to allow you to roll the VM back to the starting state several times, as you attempt to follow along with your written steps. Assume nothing, and test each step with malicious ignorance.
Those are the types of blog posts that I write and the reasons behind them. I have attempted to force different types of articles for different audiences in the past, but when I am doing something that isn’t natural for me, I tend to lack motivation. My job is not to write articles, my job is to help write software to solve problems. Writing blog posts like this one and the ones described above help me be a better communicator, ensuring that the solution we are implementing is solving the right problem.
Afterword: Ok, that is over my 1000-word goal, but that is not the entire writing process. There are two important steps that I have not covered. Editing and peer review. It has taken me around 2 hours to write out my first draft of this article. After I complete an article, I let it sit for a day or two and then come back and re-read it for content and clarity. If it is an article that I am publishing on my own blog then I will upload it and schedule it to publish. If it is an article that I am intending to publish in a different forum then after I have made my edits, I will send it out to a couple of peers to proof before publishing.