Home
Blog
Contact
Resume for Steven E. Newton
Papers
Readings for Code Janitors
Services
Steven E. Newton
Crater Moon Development
© 2003-2023
Writing as a Programmer
A Brief History
Like many self-taught programmers, I wrote minimal documentation early in my career. Nobody pressed me for it, either. That’s probably a reflection of the (im)maturity of my first employers. Most of my work-oriented writing was email, and a few usenet posts.
Why write? Smaller, co-located teams can discuss problems and solutions in front of a white board, but it doesn’t scale up, and I have yet to see a working solution for distributed environments.
It was many years before I started taking the writing part of programming seriously. Writing things down forces you to clarify your thinking. The cartoonist Richard Guindon said, “Writing is nature’s way of letting you know how sloppy your thinking is.” It’s kind of surprising how easy it is to believe you have a clear understanding of the ideas when they’re in your head, but then discover it’s a struggle putting them into words and communicating your understanding to others.
Writing, then, can be done to enhance one’s own understanding. Clarifying my own understanding became a significant motivator for me when I was tackling difficult or expansive subjects.
I’ve been keeping personal journals and diaries for a long time. Personal journaling is a forgiving, stream-of-conciousness recording of thoughts. It’s not as demanding as writing technical documentation, but it is writing, and I studied journalism in college, so I had writing experience, but I hadn’t done it for technical subjects.
Difficulty writing may be a side-effect of schooling, where we are asked to write an essay about a some subject, but without considering the audience. We’re freed to stick with writing what we know. This knowledge-telling is easy for simple things we know about which we have considerable relevant information, but harder for things where we have less familiarity, or are more complex. The result of a round of knowledge-telling might pass as material for a first draft. This form doesn’t consider the needs of the reader, making it difficult to convey the ideas.
"…the hardest problem in software engineering is getting the appropriate information into the heads of the people who need to have that information in order to do their work effectively."
Writing Like a Programmer
We can use an analogy to illustrate technical writing as programming. Is there something like a unit test for writing? Yes, there are goals and there are measures of progress towards the goals. An introductory section is like setup and initialization of a program. Each sentence, paragraph, and section should relate to the whole. Excess words are like verbose code.
Good writing starts with goals. Goals against which the progress of the writing can be tested. These goals are not about the total length of the writing, but about whether or not it communicates the ideas clearly, if it covers the material sufficiently, and if it is clearly written at a level appropriate for the audience.
Writing As a Technical Expert
For the purposes of this note, documentation refers to writing intended for other technical people – software engineers, devops folks, test engineers, and so forth – rather than user-facing documentation. This writing is about the internals and technical details of what and why. A few of the kinds of documents programmers write for others:
- Conceptual overviews
- Case studies
- References
- Best practices
- Discursive explanations
The Steps
Having Something to Write About
Have something to write, not in the sense of “have a subject in mind” but in the sense of having usable raw material for writing. Keep a notebook. Jot down ideas.
Broadly, there are two kinds of ideas. First, ideas about what you know or learn. The foundational content for writing. Second, ideas for what to write about: because you fancy it necessary; for work; because it’s interesting and you want to; or for no other reason than finding yourself with enough of the first kind of ideas to amount to an article or technical memo.
In my system, the ideas for what to write about become project ideas, as C. Wright Mills describes in his 1952 essay, On Intellectual Craftsmanship. Capturing the ideas when I have them ensures I can find them later, when I need to write about the topic, have a starting point, and avoid blank page syndrome.
Distill Ideas Into an Outline
Once you have enough ideas in your notebook for something to come together, tease out an outline for what you’re going to write about. Don’t try too hard to get the outline perfect, get something to guide writing.
For outline-haters, don’t fret. Just write a handful of key terms or phrases you would expect to use.
In the programming analogy, this would be like creating a design, or writing the first tests.
Getting Words Written
Just write, forget about grammar, spelling, organization, or whatever. Put words down, as your ideas flow. Use the content from your notebook as your starting point, even copy and pasting directly into what you’re writing. Don’t overthink, rewrite or organize. If you get stuck, make a quick paraphrase or note about where you are stuck. If the document seems to need an illustration, graph, or something, don’t stop to create it, breaking your flow, stick a marker like [diagram goes here] in your text and move on. Don’t worry about being polished, the goal is to get your ideas, your thinking, down into something resembling phrases, sentences, and paragraphs, or near enough to make raw material for later.
Turning the Draft Into a Product
Let it sit for a while, a whole day, a week, however long it takes to get perspective. Now, look at what you wrote, and create an outline for what you’re trying to say. Decide what the main point is, and tease out the supporting arguments. The main point states the case for what or how to do something. The supporting arguments say why the main point is good. Using the Five Whys can help tease out supporting arguments.
Write the introduction and conclusion.
Cleanup
Edit. Re-organize all the rough draft stuff to fit the outline. Redo the outline if it makes sense. Make the whole fit together, provide the usual sorts of transitions and structure.
Publish.