Principles of writing as a software engineer

This guide is in progress.

Like the acts of software development, writing for software engineering has precepts or principles, guidelines.

These principles are split into two segments, “Tooling” and “Actions”. Tooling is mise-en-place, the support system that’s personal to you to accomplish your work. Actions are the doing, the writing itself.

More detail and structure will be built from these foundations.

Tooling

1. Write with local tools you know, trust, and respect.
2. Favor writing in plain text that you can export anywhere when you need to.
3. Back-up your writing.
4. Resist impulses to complicate your writing tooling at the expense clarity and productivity.

Write with local tools you know, trust, and respect

Favor using a text editor you love as a preference to writing directly in a messaging application, email client, or web form in a browser window. I trust a local text editor with a local file system can predictably handle text files, may possibly handle failures modes well, can be backed-up, run through other tooling like command line utilities, etc. It also offers the predictability of knowing when you’ve saved state.

I have directly experienced and seen other experience writing text of varying length and importance directly into a content management system, a web form, a chat window and something goes sideways. Sometimes, the webform autosaves and doesn’t tell you. Then, sometimes it doesn’t or reverts to a previous state with no apparent mechanism to repair that state. The application crashes, the computer freezes. And so it goes, that the previous half-hour of thinking and writing is as corporeal as smoke.

I do this for code review feedback that’s longer than a sentence or involves providing sample code as feedback. I’ve spent a lot of time getting familiar with how to use my text editor. Workflow adjustments, available commands and such. It’s a far richer and consistent experience working with text, words, paragraphs, code examples, etc. than I’m going to have trying to approximate any of it in a browser <textarea>.

Favor writing in plain text that you can export anywhere when you need to

Most of the time, I prefer to work in Markdown files saved directly to disk and then synced, but applications that store text as database entries and easily allow exporting plain text to such a file are also fine.

Back-up your writing

Supported, automated, offsite systems are best, but even manually copying files from your primary machine to an external drive, cloud storage, a Time Machine backup, or a Git or Mercurial project that you can push elsewhere would work.

Resist impulses to complicate your writing tooling at the expense clarity and productivity

It’s quite easy and tempting to switch text editors, knowledge managers, scripting engines, organization schemes and so on. Choosing and iterating on each of these are necessary, to a point, but let decisions be enough to facilitate starting and building momentum and not act as infinite building of structure. We are not building a content management system for our personal websites here.

Actions

1. Writing is an act of thinking.
2. Not all writing needs to be shared with anyone or stored forever.
3. Good writing is spontaneous.
4. Good writing is iterative.
5. Remove clichés, filler phrases, and throat clearing.
6. Be honest both with your audience and yourself.

Writing is an act of thinking

Just as having a second engineer present to talk through a problem as a “rubber duck” can help unstick a code issue, writing out your thoughts can unstick your mind and uncover your opinions and hypotheses.

Not all writing needs to be shared with anyone or stored forever

Some writing is strictly ephemeral. I’ll write about development journaling elsewhere, but think of a note pad, scratch paper, a running text file as a REPL for phrasing. Keep it if it’s useful to you, discard it if it isn’t. Practice and experience will help you distinguish the two.

Good writing is spontaneous

Writing is thinking, but don’t overthink the process of what you’re writing. I find it helpful to stay loose and let words flow first to see how I’m trying to articulate my ideas. I may also keep notes within the writing itself about what I want to fact check, look up, fill-in and so on. The key is writing while you feel the charge to do the writing with the aim to get a draft down before distractions elsewhere, running into mental blocks, etc.

Good writing is iterative

This sounds oppositional to “Good writing is spontaneous”, but it’s actually complimentary. A first draft is the starting point for a more polished piece. Editing immediately is possible and may be enough for shorter and more ephemeral text. Editing after a break, potentially with multiple passes, makes sense for more durable text.

Remove clichés, filler phrases, and throat clearing

There’s definitely a process of writing to get the thoughts out, but I find I need to go back and rewrite in order to change-up sentence structure, paragraph order, and remove things that frankly aren’t moving my thoughts forward. Clichés are crutches, filler patterns are empty words, throat clearing is finding a wind-up to actually start what you want to say. Note, though, providing essential background and context is not throat clearing. Where feasible, if more context and background knowledge is needed, link to something else with that additional information.

Be honest both with your audience and yourself

When creating an outline, take stock and write down your expected point-of-view, the experience you have with the subject at hand, any strong emotions you have about the subject, the circumstances, and your audience.

• What data do you have at hand or might be available?
• What supports and detracts from your position?
• Where is there clarity and where is there uncertainty?
• Are your motivations, benefits, risks, and concerns aligned with those of the audience or are they different?
• Is it reasonable for those points to have alignment or is it more reasonable for some differences that need to be addressed in some fashion?

Provide your audience, including future you, the background and framing necessary to understand what you’re writing as completely and as clearly as possible. In a code review, this is likely substantially provided the pull request context itself, but don’t shy from writing more than might otherwise feel like “enough” if the pull request was treated ephemerally. Same thing when presenting a business case, a technical decision record, or a post-mortem document. In all cases, seek clarity and completeness without evasion or obfuscation.