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 feel obligated to write about writing. Writing a blog post is a lot like writing an essay. It has been years since my college English classes, but a quick Bing search about essays gives me the refresher I need. I need to start with an introduction (this paragraph), follow it with a couple of 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 is something that you should do for a couple of different reasons. The first reason is to help solidify the knowledge by forcing yourself to express it in a form that is accessible by an audience other than your peers. Providing an understandable context of how and why programmers approach problems in the way that we do has value. The more the customers for our software know about what goes into creating it, the better able they are 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 work that you have done for the various clients that you have worked for. 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. It is often more important to be honest about what didn’t work than it is to promote yourself by only reporting what succeeded.
One way that writing a short form article about something that you want to learn about helps is 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. Writing an article on how to use a new language feature to implement a solution to an existing problem is a well sized example. You can also write an article 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 by how close you come to solving it. Measure your success by the existence of an article. When you finish writing the article, you have either achieved your desired result or you have documented a method that does not work. This allows success even if you don’t solve your problem, which is a great motivator to write more articles.
You are a consultant or a developer and not a college professor, so your research needs to focus on attainable types goals. How to solve a problem that you don’t know how to solve using a technology that you are already familiar with or solving a problem that you are very familiar with utilizing a new technology. College professors and other researchers are charged with pushing the boundaries of human knowledge while 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.
Limit myself to one week when writing about a subject you want to learn about. This is long enough for you to do a couple of 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 you should ask for some guidance or a push in the right direction. If you don’t have something available to you at work then join a local user’s group or find 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 optimum time might be different than mine.
Finally, writing about a subject that you are learning about also helps you 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 then 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 which helps me ensure 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.
(Originally published elsewhere, at another time. But since the original location no longer exists...)
