May 2024 - Spinning Code

Writing for Developers and Consultants: Know your Documents Types

When I started this series on writing for developers and consultants, I thought of this piece first, but I couldn’t get the ideas to come together. Sometimes it takes a few tries.

Anytime you write something, you should be aware of what kind of document you’re writing and who is it for. The definition of “document” in this context is very broad it could be: an email, letter, solution design, chat messages, blog post, test script, work of fiction, book, poem, presentation, marketing slide deck, scope of work, and so on: anything that involves writing words.

For example, this is a blog post, about writing, meant for people who are developers or technology consultants who may have been told good writing isn’t important.

Common Work Documents

I’m going to put aside poems, novels, and other personal writing forms to focus here on work related writing. Developers need to be able to describe their work to other people. We also need to communicate about what is happening on a project, support one another, and ask for help. We do all these things with words, and often in writing.

In my career I’ve written a wide variety of documents as part of my work. A partial list (because I doubt I can think of everything to create a complete list) includes:

Emails
- to my boss
- to colleagues or friends
- to direct reports
- to clients
- to large mailing lists
Solution Design Documents
Scopes of Work
Contracts
Invoices
Test Scripts
Conference Talks
Research Reports
Chat Messages

Some require more detail and longer prose than others. Some are expected to be polished where others can tolerate typos and mistakes. But each has its own style, structure, audience, and expectations that the writer must meet.

A Document’s Purpose

When you start to wring something, know your purpose in writing.

Not all documents are created equal and so understanding your purpose is critical. Are you writing an Solution Design that needs to outline how you plan to solve all the hard problems in a project? Or are you writing an email to your boss asking for a few days off? Is this a research report meant to support an advocacy project or a cover letter for a resume? All of those are important things, but none should be written in the same tone or with the same style.

A Scope of Work (SOW) is a lasting artifact during a projects that sets the bounds of the work you’re going to complete. A sloppy SOW can cost you, or your employer, vast sums of money. A SOW writing purely to defended against those concerns may not express the client’s needs and interests, and result in them refusing to sign.

An email to a client might be a friendly reminder about pending deadlines, or a carefully crafted notes from a contentious meeting. Written well, both could leave you in a better place with your client. Written poorly, both may cause your client to become frustrated with your sloppiness.

If you don’t know why you’re writing something, you are likely to write the wrong thing. At work, if you aren’t sure, ask for guidance.

A Document’s Audience

There is no such thing as a “general audience” you should always have a mental image of who you are writing to, and why.

We all know that it’s important to think about your audience, but we don’t always do this well. In part because determining the audience is sometimes a little complicated.

When your audience is the person or people you are writing to, you need to leverage your understanding of their knowledge, skill set, and project engagement. You want your text to meet them where they are.

Sometimes the audience you care about most isn’t the direct subject of the message, but a 3rd party you know, or suspect, will read the document later. I find this is true particularly in contentious situations.

FOIA Warning

If you work in, for, or with government agencies in the US (and for similar reasons elsewhere as well) – including as a subcontractor – you should understand if your content is subject to a Freedom of Information Act requests. Sometimes your audience isn’t the person you are writing to at all, but the reporter who could read the message 2 years from now after they get copies of everything related to your project. In those settings, don’t put anything in writing you don’t want on the front page of a major newspaper.

But FOIA can also be a blessing for a developer who knows a bad decision is being made. Carefully worded expressions of concern, and requests for written confirmation of next steps, can trigger FIOA-cautious readers to recognize they need to follow your advice.

Finding the Right Level of Technical Detail

One of the hardest things for developers, and other people with lots of technical knowledge, to do well is communicate clearly about technical minutia. There is a balance to be struck between providing transparency and overwhelming readers with details. Developers have to think about details in our work. We also use field specific jargon that can be confusing to people whose work is in other areas.

Too often we confuse that specialized knowledge of our field, with intelligence. I have watched developers lose their audience in the nuances of small details, and come away announcing their audience was a bunch of idiots. Early in my career I was guilty of this as well. Assume you’re audience is as smart as you; they just know different stuff.

When you make that assumption you can avoid talking down to people, and start to work on finding their level.

The right level of technical detail will also vary by document type. When I’m exchanging emails with a client’s in-house developer we go deep into the weeds often. When I’m writing a SOW, the technical detail is nearly absent as we are defining functionality and purpose, not the exacting detail of how that functionality will be delivered.

The more you can be in conversation with the people you’re working with about their background, the easier it will be to find the right level of detail to explain yourself clearly.

Summation

Hopefully by now it’s clear, this is an overview of approach, not detailed guidance. In a future post I plan to write about some of these specific documents types, and how to write them. Hopefully this overview gives you ideas and things to think about as you work on your next document.

As I said in my first post on this topic, communications skills for developers and consultants is an enormous topic. The plan for this series is evolving as I go. If you have suggestions or requests feel free to leave me a message.

Tool Building Mindset

Earlier this month, at Mid Atlantic Dreamin’ in Philadelphia, I gave a talk titled Software Super Heroes: Building the tools you wish you had. My goal with the talk was to convince people that should, can, and in fact do, built tools for themselves. If you work with technology, and your job involves repetitive tasks the same applies to you too.

What do I mean by “Tool” and “Tool builder’s mindset”?

I like to use a very expansive definition of tool: “A tool is anything that makes a task easier which would be repetitive, hard, or impossible without it.” In that sense just about anything you make that simplifies you work can be considered a tool: a project estimation spread sheet, a good set of directions for a complex task, a flow for a Salesforce admin, a piece of code to normalize a large collection of files, and more.

My intention with that expansive view is to help encourage people to take on a tool builder’s mindset.

To be a digital tool builder does not require knowing how to write complex software, it just requires you to do what you already do now, but with intention. When we use a broad definition of tools, it’s easier to see ourselves as tool builders, even if we’re just talking about a spreadsheet or a Salesforce flow meant to handle an administrator’s daily tasks. When we see ourselves as tool builders we are more likely to make something worth using more than once.

Why does this matter?

When we approach problems with a tool building mind set, instead of insurmountable challenges caused by gaps in our tooling, we see opportunity to create something new to make the impossible possible. Instead of facing hours of boring repetitive tasks, we have chance to build a more interesting special purpose solution.

Fight the Tool Building Excuses

There are several excuses I commonly hear from people when I encourage them to build their own tools. They range from concerns about not having the right skills, to assuming someone else already built that tool or that the time required isn’t worth the effort.

My general response to these concerns is that while people should indeed look around for tools that already solve their problem, and that some problems are very hard to solve completely, if you start to chip away at a complex problem you often will find that you can create tools that are good enough to save you time and effort.

Don’t try to build the perfect tool that solves all possible edge cases on your first go. Create a tool that takes out some annoying and repetitive task. Then create a tool that solves for another task, or builds on your first time. Chip away.

I often tell developers who are early in their career that I should never see them doing rote repetitive tasks for hours on end. Instead once they understand how a repetitive task is done, they should start thinking about how to build a tool to take over. But that’s not just advice for developers: we invented computers to do repetitive asks (calculating artillery firing tables and cracking codes), let them do that.

Pick Your Tool Building Path

When you set out to create a tool you have two main options: use something you already know, or use tool building as a chance to learn something new. I’ve used tool building as was to teach myself new features of Excel, Google Sheets, Salesforce Flows, Git, and several programming languages. This can be a great way to learn how to use the tool that’s just right for the job. But learning a new tool or technique takes time, and if you have a deadline you may need to move faster.

Personally I try to take both paths from time to time. I use things I know when: they are exactly the right tool, I am under time pressure, or I want to keep my skills sharp. I will take the time to learn something new when: it’s something I need to learn anyway, I am building on my own time, or it’s exactly the right tool for what I need to do.

Neither path is correct 100% of the time. By using them both I am able to create the tools I need, and broaden my skills over time.

Just Start Building

The next time you’re faced with a task that is repetitive or hard with the tools you have: create yourself something new. Don’t get hung up on being perfect, just create something that’s better than what you have at the start.

Then save your tool to use again later. Share it with colleagues, friends, or as an open source project.

When in doubt, just start building.

Writing for Developers and Consultants: Use of Language

Words matter.
Grammar matters.

How we use language affects how our audience perceives us. In school teachers and professors taught many of us formal – and strict – rules for writing. Those rules are useful to know, but my point is not that you need to follow them strictly.

You need to control the language you use with intention, and create the impression you want your audience to have.

When we write at work, we are a reflection of ourselves, our team, and our companies. We want all those things to look good to our clients, customers, leadership – our audience. That is not the same goal as learning all the rules of Strunk and White. It’s about choosing the right words and structures to meeting our audience’s expectations.

To do this well, you need to understand the patterns and rules people think of as formal writing, and when to use idioms or patterns that break those rules. Sometimes it is better to follow the rules; sometimes it’s better to break them.

It’s a matter of fashion, pure and simple. People do need to be taught what the socially acceptable forms are. But what we should teach is not that the good way is logical and the way that you’re comfortable doing it is illogical. It should just be, here is the natural way, then there’s some things that you’re supposed to do in public because that’s the way it is, whether it’s fair or not.
John McWhorter

Strategic Use of Passive Voice

In college several professors demanded I never use the passive voice in my formal papers. Microsoft Word of the day backed up that assertion by flagging every passive sentence as a grammar error. In those papers they were right, since they controlled the grading standard, but those are not the rules I follow today.

Shortly after graduation my wife and I discovered the power of the passive voice when our rabbit chewed through a power cable of our brand new printer. When I called support I said: “The power cable is frayed.” They didn’t ask how the cable became frayed, they just assumed it had arrived that way and shipped us a new one. Perhaps not our most ethical moment, but a useful one in understanding the power of breaking the formal rules we’d been taught.

A simple definition of the passive voice is:

A passive construction occurs when you make the object of an action into the subject of a sentence. That is, whoever or whatever is performing the action is not the grammatical subject of the sentence.
UNC Writing Center

The classic joke is “Why was the road crossed by the chicken?” where we have clearly reversed the subject and the object of action. More commonly we leave the true actor, the person who should be the subject of the sentence, out of the sentence entirely. There are lots of discussions on the passive voice around, because it is an important concept to understand. But banning passive sentences is the wrong approach.

Passive construction makes sentences weak and frequently unclear. Without editing I will often write too many passive sentences in a post. But sometimes the weakness of passive construction helps to drive my point home.

In writing with clients over use of active voice can become accusatory. Think about the difference between “The data set provided has many errors.” vs “You provided me a data set with many errors.”

The first gives the reader room to blame a file, a process, or another cause other than themselves (which may be correct). The second points a finger. When I am trying to resolve a problem caused by bad sample data, pointing fingers, placing blame is not helpful. Sometimes we need to be clear, and identify actors explicitly. Sometimes we want to indirect to avoid creating unneeded tension.

Other Rules to Follow Strategically

In school our teachers taught many of us that paragraphs should always have three, or more, sentences that mirror the three sections of a paper: introduction, body, conclusion.

But a sentence by itself stands out and draws attention.

If every sentence were by itself they would stop standing out, so mixing emphasis and longer structures is still a good idea. The readability checker I use for my blog dislikes long sentences, preferring short choppy structures. Short punchy writing is easy to skim, but exhausting to read. Overly long sentences are hard to follow and may reveal incomplete thinking because they contain too many ideas. It’s a balance to be used carefully.

Punctuation is also taught as a series of strict rules. However use of commas, semicolons, periods, dashes, and so on are also matter of personal style. If you know the purpose of a mark you can decide when you want to use which to add emphasis and clarity to your text.

Starting sentences with conjunctions was most gracefully debated in Finding Forester (movie staring Sean Connery as an aging writer teaching a young African American boy how to become a writer):

Forrester: Paragraph three starts…with a conjunction, “and.” You should never start a sentence with a conjunction.

Jamal: Sure you can.

Forrester: No, it’s a firm rule.

Jamal: No, it was a firm rule. Sometimes using a conjunction at the start of a sentence makes it stand out. And that may be what the writer’s trying to do.

Forrester: And what is the risk?

Jamal: Well the risk is doing it too much. It’s a distraction. And it could give your piece a run-on feeling. But for the most part, the rule on using “and” or “but” at the start of a sentence is pretty shaky. Even though it’s still taught by too many professors. Some of the best writers have ignored that rule for years, including you.

More or less any rule or pattern you have been taught, you should explore when to follow and when to deviate.

Practice Until Your Comfortable

I know of no magic way to become comfortable using language carefully, except by doing it. Be thoughtful when you write. Edit carefully at every chance. Ask for feedback when available. And write in as many contexts as you can justify.

My whole point in keeping a blog, even well passed the era of independent tech blogging (and with limited care for the theme being used, SEO, or monetization) is to force myself to write regularly. I write different types of posts with different styles and attention to care. Some of that is months I’m being lazy, and some of that is very intentional.

I first wrote for this blog when I had a job that actively discouraged me from communicating well – I was told time and again that developers cannot write clearly. That’s crap: it was then, and it is now. So I started writing at least monthly to keep myself in practice.

Your practice does not need to be a blog. Find yourself some form of routine writing, and play with your style over time. Just a few suggestions of things to try:

Letters to friends and loved ones (on actual paper and with a stamp)
Short Stories or other fiction writing
Contribute project documentation to an open source project
Essays for Medium (more or less blogging with less commitment)
Participate in an online writing challenge
Journaling
Take a writing course

Still More to Come

As I said in my first post on this topic, communications skills for developers and consultants is an enormous topic. I have not yet planned the series, but you should expect more to come.