Writing for Software Engineers Read Me First

Developers should share more knowledge with their peers. Follow these tips to overcome anxiety and start blogging (or write better).

Translated from Writing for Software Engineers: Read Me First by Charles Humble. Very good writing textbook, the previous one is "Google Technical Writing" translated by Mr. Chen Hao, and I also remember Mr. Chen Hao here. Find the second part here. Many of us engineers suffer from a common ailment: fear of writing. This usually starts at school, where we are told that we are not "gifted in language". This is nonsense. Writing is a craft, and its principles can be learned.

There are many reasons why you might want to do this.

As more of us move to remote and hybrid work, the ability to communicate clearly in writing becomes more important than ever. Writing can be a fantastic way to build a personal brand, and in the process it forces you to learn and develop. Improving your writing skills can also help you advance in your career. If you aspire to work in management or developer relations, want to make yourself a conference speaker, or even dream of one day writing a book for a technical publisher, writing (and the aforementioned branding) is central to achieving those ambitions. Also, it gives you a reason to talk to other knowledgeable people, and it's stimulating, fun, and difficult. I think that, as engineers, we are drawn to difficult problems. There are also some striking similarities between writing and programming. Some are obvious. As with programming, writing can be improved with practice. As with programming, you often learn new writing skills by imitation. Like programming, there are patterns in writing that can come in handy, but these patterns are also tempting, confusing, and prone to overuse. Your subconscious mind also does more writing (or programming) than you think. You might spend the whole day struggling with a question in an article — or a paragraph — only to figure it out right after the break.

I strongly believe that engineers need to improve their ability to share our knowledge, and writing articles is a key way to achieve this. As a former engineer and CTO, and now primarily a writer and consultant, I'm going to share my approach in the hope that it will encourage some of you to share more of your knowledge.

With that in mind, I'll start by breaking down my writing process. Of course, everyone's creative practice is slightly different. But thinking about how someone handles work can be a useful starting point.

I like to start by thinking about who I'm writing for. I've found that it helps to have a clear person in mind before you start. One of the benefits of this is that you can answer questions such as, "What do they know?" And "How much do I need to explain?" "Such a question.

For example, you might be thinking, "I'm writing this for a senior developer in his first leadership role." They've probably been coding professionally for about seven or eight years, but haven't led a team yet. ”

Or, "This is for junior developers – maybe first or second jobs – who use AWS Lambda for their first project." They know GO because they studied it in college, but they don't know much about building lambda projects. Of course, "this is an article for people like me from two to three years ago, before I get to know these things" is also a good (and common) place to start.

One reason to know who you're writing for is that it helps you identify terms that aren't familiar to some or all of your target audience. If a term is unfamiliar, you can:

Link to a good explanation (don't re-emphasize the bright wheel).

If you can't find a good link, provide a short definition.

If you have a lot of these terms, it's a good idea to provide a glossary. Once I've decided who I'm writing for, I'll decide what role I'll play for that reader. Am I a journalist? Educators? Just an ordinary programmer?

And then I asked, "How much do I want to cover, what is the one thing I want to say?" "This is important because all writers aspire to completeness and accuracy. My best advice here is to think small. Decide which little corner of the topic you want to cover and do it as well as you can.

The next question I asked myself was, "What is written?" ”

I recommend setting a word budget at the beginning. For example, 500 words is good for launching a new tool or product and giving a brief description of its features – basically, it's a news story. For blog posts or similar articles, 1000 to 2000 words is the standard word count. Tutorials (especially those with a lot of examples) and written interviews or interviews can be a little longer, but always keep it concise.

If an article really ends up being too long, consider whether you can split it into two or more parts. But be aware that the internet is flooded with first part articles but not a second part, so try to write the entire article before publishing the first part.

There are a few other decisions that need to be made beforehand. One is, do you want to write in the third person (as an observer) or in the first person (as a participant)? A related question is what tense you intend to use; Most people write primarily in the past tense ("I tried to write in go the other day"), but you can also try writing in the present tense ("I was sitting on a plane to San Francisco while hacking some go **").

Whatever you decide to do, stick to it. It can be uncomfortable for the reader to switch back and forth between perspective and verb tense in a paragraph.

Another thing to consider ahead of time is whether you need to conduct any interviews. For your own blog, and often for corporate blogs as well, you'll be expressing a point of view. For external publications, you're more likely to need more than one and conduct interviews to get. It's very helpful to maintain your network here so that you have a network that you can easily connect with.

Before any interview, I usually write a rough first draft in order to find out what gaps I want to fill. Then I would pre-plan the issue before contacting. The interview combined pre-planned questions with impromptu conversations, but I found that planning was essential to get a good outcome.

Conduct interviews via email, via conferencing platforms like Zoom**, or in person. I used to gravitate towards email, but as my experience grew, I started to prefer interviews over calls. Rather than scrambling to take notes by hand, it's best to record ** or ** interviews with the interviewee's permission, and some artificial intelligence (AI)-powered applications can provide speech-to-text transcriptions, making it easier to cite accurately**.

If my experience as an editor is anything to back in, writers seem to have a strange sense of dependence on their initial drafts. Try to avoid it. Instead, think of your initial draft as exploring your problem domain through methods that work for you, rather than writing test cases or drawing UML diagrams in the first place.

When you start writing, you'll often find that the material flows in directions you didn't expect, and some of the upfront decisions you make may not be the right ones. It doesn't matter. Let the footage take you where it wants to go, then review and refine it later.

When I start a job, I don't think too much about where it's going. I find blank pages daunting, so I tend to write text on a screen or paper without thinking too much about it, and then organize them once I get the drafts.

I've also found that my writing style is very different if I write by hand instead of typing on a screen. I usually work with a computer, but I feel like it's worth trying both methods and figuring out what works best for you. I'm dyslexic, so I try to write by dictation, but the results are never satisfactory to me, but you might get a different result.

You have to be good at discarding the material. I often find that I end up deleting the first two or three paragraphs of the original draft because they weren't good enough; Heather Joslyn, editor-in-chief of The New Stack, refers to these one-off passages as "throat clearing," which I love. You'd be surprised at how many articles I've edited, in which I'll cut out the first few paragraphs as the beginning. I'm drafting in Pages, partly because I use a mac and partly because I don't find it obtrusive, but mostly because I know I'll submit this post somewhere else – usually in the form of Markdown, HTML, or Google Docs, depending on the publisher. This is similar to making a one-off prototype for an application, which we don't often do in the real world, but can be useful. In a masterclass on the art of storytelling, author Neil Gaiman said, "Doing your second draft is the process of making it look like you've been doing what you know." "I usually go to Google Docs for a second draft because it supports tracking changes and version control, which helps with editing, allows for comments, and is great for collaboration. The open-source Docs to Markdown plugin, while not entirely without its vulnerabilities, is generally good at extracting text from Google Docs into HTML and Markdown, depending on what your content management system needs. The second draft is where I started to think about the structure of the work and whether it was logical. This is where understanding your readers really starts to pay dividends, because you can ask yourself questions like, "What does this person want to know in the first place?" "Such a question.

If I'm working without an editor, once I'm happy with the manuscript, I'll find someone else – usually my tormented wife – to read my second draft. If I work with editors, I usually send them a second draft.

Before publishing or submitting, I usually send a draft to anyone I've interviewed to make sure they're happy with their quote. It helps nurture contacts in future interviews and helps prevent lawsuits. I also often receive useful feedback this way; I've only had one major issue where a respondent wants to make a lot of changes.

If you've read the Gang of Four design patterns book at an impressionable age and found yourself using factory methods and decorators everywhere in **, you'll be familiar with one of the problems with patterns: they're useful, but overuse them tempting. Formulaic writing has a bad reputation, but journalists, like all writers, sometimes rely on tried and tested patterns, and I don't think there's any harm in learning some.

The inverted pyramid structure is one of the most widely used modes of writing. It is commonly used in journalism, but it is also widely used in various other types of text, including blogs, editorial columns, and marketing materials.

Think of it as a descending hierarchy of importance. Start with the most valuable facts, then use paragraphs to support the argument, and go deeper and deeper the way on.

The key to this structure is the opening paragraph, which should summarize the most important information in a clear and concise way to pique the reader's interest.

In this structure, the most important sentence is the first sentence. If your readers don't want to read the second sentence, your article is already cold. The trick is to write sentences that hook the reader and keep encouraging them to read to the end.

Here's an example of a news opening written by The New Stack's news editor, Daryl K. Taft:

"Despite the recent uproar about Microsoft not using the C programming language much for the sake of Rust, Microsoft says it's still committed to C

Narrative writing is often used for close-ups in newspapers and magazines. There are two parts to a narrative: a story and a storyteller. The storyteller is more like a playwright or a home – depicting people interacting with each other in a vivid environment. It is not often used in technical writing, but it can be an effective way to write case studies, eg.

The challenge with writing this kind of text is that you can forget the news story you're trying to tell. Often attributed to journalist and writing coach Roy Peter Clark, the hourglass mode aims to combine the best of narrative and inverted pyramid style. The hourglass story is divided into three parts:

An inverted pyramid that summarizes the most noteworthy information at the top.

A storytelling that allows the writer to unfold the story in depth and detail.

A transition, or hub, that marks the transition between the two formats.

The Focus style has been used by Wall Street for many years, often for front-page features.

Like the hourglass, the broad goal of the Focus style is to try to blend narrative storytelling and news writing styles. It is divided into four parts. The first part is the key introduction, which is not like an inverted pyramid and can be up to five paragraphs long. The second part is the conclusion paragraph, which gets its name from the fact that it summarizes the story "concisely". The concluding paragraph states the core part of the story and how the lead makes the point.

The core point is then elaborated in the main text, while the ending leads the story to a natural conclusion with memorable twists or comments. My article "Averting the Catastrophe of Success: The Battle of Ticketmaster Taylor Swift" shows how it works, where the conclusion paragraph appears in the fifth paragraph, marked in red below.

In technical writing, this style tends to vary slightly, using anecdotes or stories as entry points and guides, and then moving on to the core of the essay through key paragraphs as stylized twists. Part of the reason why this approach works is that humans are naturally fond of stories; It's also effective in conference presentations, which is why most TED Talks start with anecdotes.

You can see how it works in Jennifer Riggins' article "How to set fire to a troll farm". Before the key passage acts as the fourth turn, she focuses the narrative with three paragraphs (indicated by the red border below).

The term "ending" refers to the end of the story. The ending leads to endless questions. I think one of the reasons is that in school, we are taught that articles have a beginning, middle, and end, and that the ending should be a retelling of what we have already said in a more concise form.

When you put "conclusion" in a subheading, or write something like "All in all, you can point out......You'll know you're doing it. At this point, your readers will hear your entire article squeaking.

Such a conclusion would undermine any good work you've done so far. A good ending should feel like a natural place to stop. One trick I use is to review my notes and see if I can find any natural reasons that feel like ending this post. Here's an example from my article "About Ecstasy, a language designed for the cloud" from The New Stack:

"We've been working on it for about six years, and we're only now starting to build the actual project that we set out to build," Purdy said. "It's the longest road to a minimum viable product you've ever heard! ”