Once you start writing an article or blog post, how do you polish it so that readers will crave it? Get some tips in the second part of our series of articles.
Translated from Writing for Software Engineers: Beyond the Basics 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 first part here. If you write for the internet, the only thing most people will read before deciding whether or not to click and read your article is the headline. A good editor can help you with this, and I'm convinced it's their responsibility, but if you're trying to come up with a headline on your own, a good test is to ask yourself, "Would I read this headline without context?" ”
For example, a headline like "Regulators Will Like You" might not work – what does it mean? Some better titles:
About Svelte, the much-loved state-driven web framework "How Typescript Wins Developers and the J**Ascript Framework" Once your article disappears from the first page, almost all of your traffic is likely to come from Google searches – the title is probably the only thing your readers will see before deciding whether or not to click on it. Use words in your title that readers are likely to search for; Note that Svelte, web frameworks, TypeScript, and J**Ascript are used in my example. This naturally sparks a discussion about SEO, but SEO is such a huge topic that I won't discuss it here. Focus on producing as good content as possible and trust that if the content is good, Google will find you. As I mentioned in the first part, it's important to consider whether your audience might be unfamiliar with these terms, and if so, provide links or definitions. A related stylistic point is consistency. If you change the name of a variable in the middle of a method, your ** will not compile. If you change the terminology you use midway through a paragraph, the information won't be compiled for your readers. So if you call something protocol buffers, don't rename it to protobuffs until you've introduced the abbreviated version: "protocol buffers (protobuffs for short)".
Similarly, when abbreviations are first introduced, spell out the full term and then put the abbreviation in parentheses. After that, you can use abbreviations. The exception is that the abbreviation is well known. You may not need to explain RAM or HTML, but you may want to spell out the Secure Software Development Framework (SSDF) when you first mention it.
William Zinsser wrote my favorite book on the subject, "Writing Tips", and it really helped me figure out how to write clearly and concisely. I am deeply grateful to him, and I will share his message in this section. I was impressed by the quote he used, "The secret to a well-written essay is to break each sentence down into the most concise components." ”
We as engineers don't like that. We tend to make things sound overly complicated so that we can sound very smart and very important. Why call a shovel a shovel when you can call it a "ploughing gardening tool for digging"? Why is it going to rain when you can say, "We're expecting a lot of precipitation at the moment"?
The reason to keep it simple is to respect your readers.
In technology, the wider world of business, as well as the world of politics, words are often used to impress or confuse rather than explain. Bankrupt companies find themselves in a state of "negative cash flow", or the plane does not crash, but "an involuntary failure occurs", and so on.
Don't do it. Write as cleanly as you would with the method in **.
For nonfiction writing, your goal should not be to show off how rich your vocabulary is, but to convey meaning as clearly as possible. It's hard work; A clear sentence is not accidental. People who appreciate a good article will understand the work that went into creating it.
I'm particularly fond of the overuse of qualifiers. Remove them. Rather than saying "some people think Kubernetes might be considered too complex in some cases", it's better to say "Kubernetes is complex". As Zinther says, "Good writing is concise and confident." ”
Cut out the small words. I find it "a little" confusing; I was "kindly" angry. Be confused, be angry. Avoid using "easy" – if it's effortless, use "effortless".
Trim adjectives – most of them are unnecessary. You don't need to tell me that daffodils are yellow or that the soil is brown; I can guess. Of course, it would be more noteworthy if the soil was blue.
If something is worth mentioning, make it interesting to read – don't tell me it's funny; It's fun to show me it.
Writing is a visual medium that catches the eye before it enters the brain. Short paragraphs make what you're writing look appealing, while a large chunk of text can be offensive.
Of course, there's a trade-off here. A series of small paragraphs is just as annoying as a paragraph that is too long. I've edited articles that consist entirely of single sentences. Avoid this. I would say that a good default is about three sentences for newspapers and four or five sentences for blogs. But to change the length.
In each paragraph, pay attention to whether the sentence is too long. If you find yourself lost in long sentences, you may be trying to express too many ideas. A quick way to get out of this situation is to break it down into two or even three sentences.
See if you can add variety by reversing the order of sentences, replacing a novel or unusual word, or changing the length of sentences so they don't all sound the same.
Sometimes, the best way to solve a tricky sentence is to get rid of it. This always seems to be the last option that comes to your mind; If you find yourself struggling with rephrasing or clarifying sentences, you might be better off without it.
Stylistic techniques such as rhythm and alliterate are helpful. For this reason, I encourage you to read aloud everything you have written. I write entirely by ear and read everything aloud before posting.
In the first part, I mentioned my software toolchain (Mac Pages—> Google Docs—> Docs to Markdown). I usually edit HTML and markdown in a text editor, but sometimes I use DreamWe**er or Caret. I don't do a lot of image work, but I use Pixelmator Pro for illustrations. I usually conduct interviews remotely on Zoom. By using its built-in audio recording feature, I don't need to rely on my terrible shorthand. For face-to-face interviews, such as at conferences, I carry the Zoom H4N Pro with me, which I've been using for years; It's a great product, but you might just need to use one app on your phone. Since the technology can glitch, I also run backup recordings on my phone. I still transcribe quotes from interviews manually, but many writers use speech-to-text transcription services such as Otter or human-supported Rev to do the tedious work. I think most writers today are looking at large language models (LLMs) and wondering if they might be useful. I've experimented with them, but haven't found them helpful because the texts they produce are too generic and error-prone – the equivalent of Muzak's writing, or as consultant Mark Hurst puts it, Polyfilla Spackle. Given their shaky moral foundations, environmental costs, and the dangers of hallucinations and plagiarism, I think LLMs pose more risks than they're worth at the moment, and won't use them in writing. The New Stack does not use artificial intelligence (AI)-generated articles and has published its policy on this that is worth reading. Aside from software, the main tools for any writer are a good dictionary and a synonymous dictionary, and you may find grammar guides helpful. In addition to Zisser, I recommend reading "Writing for Story" by Jon Franklin and "Eats, Shoots & Le**es" by Lynne Truss. During the first Covid lockdown, I attended Neil Gaiman's masterclass with my oldest child (an aspiring ** family) to learn the art of storytelling, and we all enjoyed it all. I don't have time to dive into the SEO side of things here, but if you're interested in the topic, I found "Marketing in the Google Era" helpful; It's a bit outdated now, but the core advice is solid. The definitive SEO guide is "The Art of SEO" by Eric Enge, Stephan Spencer, and Jessie Stricchiola. I highly recommend that if you find a writer whose work you admire, then see if you are able to emulate their style; You'll learn a lot from playing around with other writers' tricks.
Ultimately, writing, like coding, is a way of solving problems. The challenge may be to get facts, organize material, or tone or style. Some patterns and structures may help, but, as with programming, you'll get better with practice.