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...)
