作者：Christian Heilmann
编译：庄七
Web writing is a professional skill. Often, you’ll find people applying the rules of other media when writing online articles or blog posts. The success rate is low.
Note that text on the web is not published in isolation but spreads across the web as bookmarks, links, and references. Therefore, it’s important to break text into digestible, quotable, and repeatable chunks and make your article titles and file headings work without the full text.
Fact: This is also an accessibility benefit. Assistive technologies like screen readers allow you to navigate a document by headings instead of listening to the entire document as one big block.
Simple Doesn’t Mean Stupid
Writing simple text is hard work. Writing impressive articles is easier. You often see people trying to impress the audience by using complex words and references. This is fine when you’re writing fiction or lyrics, and there’s a lot of fun in playing with language. However, on the web, especially in developer evangelism, your goal should be to be as understandable as possible. Consider these characteristics of simple text:
-
Writing in simple terms requires a lot of work and a thorough understanding of the subject. You need to be familiar with the subject to explain it in simple language. If you can’t explain it in simple language, you probably haven’t fully mastered the subject yourself.
-
Explaining things in the simplest possible terms ensures you reach the widest possible audience.
-
Simple wording gives non-native speakers a chance to understand the content of the whole thing and maybe spend some time with translation tools to make it useful to them.
-
Short, easily digestible sentences are less tiring to read. They also don’t look intimidating when you take a first glance. Scanning text before reading it is a very common pattern on the web–especially on mobile devices.
Warning: However, there’s a line between explaining complex things in simple terms and sounding patronizing. If you suspect you’re going too far down the “simplification” road, have someone else look at your article to avoid this problem. Read and re-read what you’ve written (with a break in between) and make it easier with each iteration. Comparisons to real-life objects and scenarios work well to simplify complex issues.
Example: At Yahoo’s “Hack Day Open”, I spoke to several members of the press who were very confused about the concept of hack days and open APIs. These were brand new things back then. Here’s how I explained it. “If Yahoo were a car company, our latest model would be taken apart here, and we would allow people to play with the parts. Maybe they’ll find a cool new way to assemble them, which is the breakthrough we need to make cars more environmentally friendly and efficient.” Tip: One tool I often use when writing online is Hemingway. You can try it athemingwayapp.com. It’s an online editor that gives you an indicator of what reading age your text requires. It flags common issues like sentences that are too long or words that are too complex.
Be Simple and Direct–Don’t Sugarcoat
Your headline and introductory text are the most important parts of a blog. Both determine how easy it will be to find this post in the future. Newspapers have conditioned us to write witty, funny headlines that include catchphrases and allusions. This is fun, but you read them knowing you’ve already bought the newspaper. Web headlines become links, bookmarks, and social media shares. Therefore, they need to make sense without other text. For a technical blog post, state what the post is about–don’t try to be too clever. Pop culture references are even worse because these don’t translate well to other cultures. Ask yourself: Do you want to be creative and witty for a minute, or provide effective information for months?
Blog posts should be like news items on the radio:
-
At the beginning of any blog, state what happened, where it happened, how it happened.
-
Continue to explain what’s in the blog.
-
Then go into details.
This will prevent any confusion and let interested people go for more. When shared on social media and everywhere, people link to your document in an automated way, and they will likely use the blog’s title–be it the title in the HTML or the big heading of the document. If your title seems meaningless out of context, not many people will click on them.
Tip: Most social networks have link previews that automatically expand links to their title and first image. This is important and a powerful thing to leverage. Familiarize yourself with the meta tags needed in your articles to get a reasonable and exciting preview on your social media platform of choice.
Content Length
Technical writing for online use is about keeping content short and to the point. People are busy and want to get to the facts.
Tip: To write good articles, write, read, delete what you don’t need, read again, delete more, and repeat. When you can’t delete anymore, you’ve reached publishable quality. If you have a lot to say, why not split it into multiple articles? This will allow you to tease at the end of the first article that the next one will be published in a couple of days and give your blog repeat visitors.
Add Multimedia Content
If you can, include relevant media in your blog. An introductory photo catches the eye and lures the brain into reading what’s happening. We’re lucky that embedding videos, audio, and slideshows is now as easy as copy-paste.
Embedding multimedia bundles our information together in digestible chunks. It also allows visitors to scan the article first and come back later to read the rest (watch the video, download the podcast). It also helps people who have a hard time reading but are perfectly capable of listening or watching.
When embedding multimedia, make sure to also write descriptive text–images need good alternative text, videos need at least a description of what they show.
Tip: Slides work a lot better by providing a text alternative or your notes. Many slides hosting platforms automatically create an HTML script for your slides. Personally, I start with my notes and then create my slides based on these notes–this way, I always have an HTML version to link to from the slides.
Structure Your Content
Structuring your content is very important. Providing landmarks for readers to scan the article structure before deciding to read your information is fantastic since people are busy.
You do this by using a hierarchical heading structure. This also helps people using assistive technologies like screen readers to jump quickly from one section to another. If you add IDs to your headings, people can bookmark certain parts of the document and send links to friends that take them directly where they want to go.
Tip: You will write much faster if you start with an outline of your headings. You can even write different parts of the article at different times. Often, when I get stuck on one part of the article and face some writer’s block, I temporarily skip it and write another part that’s easier or more familiar. Structured articles also mean using short sentences. It means paragraphs that deal with one thing at a time. It means using lists to explain step-by-step processes, or to give an overview of existing content. For large documents, it also means providing a table of contents that allows people to jump directly to where they need to go.
Timestamp Your Content
If you eat food past its “best before” date, you get sick. If you don’t timestamp your publications, they will be considered to be forever correct–even if they’re harmful by future technical standards. They will be quoted–sometimes badly–and re-quoted, taken as truth.
Example: When I started doing web development, tables for layout were the only way to build websites. You had to know many tricks to make these tables work in Netscape3 and IE4 and other “fun” browsers. I published several articles on how to do this. Now, table layouts are counterproductive for web development and actually render slower. If my articles didn’t have dates, maybe people would still consider them relevant. All the “CSS layouts are too hard “ articles certainly suggest that. Our technical environment evolves at breakneck speed. What was “best practice” six months ago is now likely considered “harmful”. So let’s make sure readers know when a document was written, even now, before following its advice.
Cite to Prove
Another important point in this section is citing other sources and linking to the content you’re building upon. By citing other sources (after reading them, of course), you validate your ideas and facts. Readers don’t have to blindly trust you–they can make up their own minds by comparing.
Pre-empt
Remember that as a developer evangelist, you are the missing link between the technical people and the outside world, and between the technical people and your own company. This gives you a task no other company department doing PR can fulfill, which I call pre-emptive writing.
What I mean is that when you talk about products, you shouldn’t “sell” them. Instead, your job is to get developers interested in them and make them your salespeople. A major task here is to anticipate the feedback you’d get if you did a regular sales pitch and answer it before it happens–pre-emptive writing.
Do not try to sugarcoat or hide negative information: instead, explain why it happens, what to do when it happens, and how to report it to the people responsible for fixing the issue.
Fact:* As developers, we are a cynical bunch, hardened by years of broken promises. An over-excited and positive description of any product won’t make us think “I must get some of this” but more likely trigger the “Okay, what’s the catch” question.* This makes developers seem antisocial, and for a marketing or PR person who did a classic pitch and is faced with a barrage of negative feedback, this can be incredibly frustrating. Your job is to anticipate part of this feedback and defuse the situation by acknowledging it in your writing. This might be a hard sell to your PR and marketing departments, but you can explain to them that by being open about the good and the bad, you can avoid a lot of confusing or bad feedback that would be taken out of context by the media and give the PR department a lot of work.
Tip: Recently, PR departments have also started to adopt the pre-emptive writing philosophy. One process I see all the time is creating a “rude Q&A” for an upcoming product release. The product’s team creates a deliberately rude and problematic list of questions and holds a workshop on how to handle them. If these questions don’t come up at the real release, great. However, if they do, you are prepared. Negative feedback falls into several categories in many cases, all of which usually present the author in an “internet tough guy” way.
Fact:* While some people are trolls who love to use negative feedback to cause trouble or “fight the system”, or try to goad people into unnecessarily prolonging discussions, others do it involuntarily because of repeated disappointment. It’s a hard balance to maintain. True trolls should be simply ignored, or as the saying goes “don’t feed the trolls”. But people can become an “accidental troll” because they post too quickly or in anger. It can be tempting to ignore negative feedback, but sometimes the wording hints at another problem that you can and should address.* Here are a few categories of negative feedback and tips to pre-empt them:
-
This simply doesn’t work for me: Make sure to define the environment needed to run the product or demo you’re talking about in necessary detail.
-
This is the same as product X from company Y: Many times this is a competitor fan. Mention that your product is very similar to others and list them. Explain in detail how they differ and why your product is not just a copy. By showing you know about other products, you prove you did your homework and still think it’s worth talking about. Don’t let people find out you didn’t do your research.
-
Nice, but I’ll never use it, no one needs it: Explain in detail what problem the product solves. If this isn’t a now-common problem but a future one, ask for feedback on how people like the product. Also tell them it’s a chance to make sure that once they encounter this problem, the product is ready and good.
-
Why are you wasting time on this when your product Y is still broken?: Make sure your writing sets the scope of the article. Talk in detail about one product. If you’re lucky, others will answer such comments and point out that it’s off-topic. If not, quickly answer that it is and point to a different thread or discussion where that person can vent their unhappiness about the other product.
-
I like this, but I don’t have the time to test it: Prepare some demos and code examples with simple feedback mechanisms that allow people to try it with a simple click, and maybe even provide a simple survey.
These are just a few examples of how full disclosure can be used to pre-empt bad feedback. There are many more, but I’m sure you’ll find good ways to handle this. Take a good look at the material you write and try to anticipate bad feedback before it happens. Any misunderstanding you can avoid by providing clearer information is potentially another happy customer.
Call to Action and More Information
When you’ve finished your article, it makes sense to end with a call to action. You should repeat resources to use, where to find more, and how to contact you or the team behind the product you wrote about.
Reprinted with permission from: Developer Relations »
