These guidelines build on editing hundreds of tech articles and observing writers of various levels of expertise and diverse backgrounds repeatedly encountering the same issues.
There are a few terms specific to old-school journalism that are useful shorthand in the editing process. The funky spellings (lede, dek) persist because they serve the same purpose they did back in the day: they get flagged by spell check (or humans!), so are unlikely to get published by accident.
One caveat: These are guidelines optimized for human readers – not SEO or indexing bots. Page ranking is secondary to producing robust content that your audience wants to read.
The headline, or hed, is the most important part of your post, at least when it comes to earning readers. Writing great heds is an art, but the perfect headline for a story is concise, engaging and active.
Concise: Don’t cram the whole story into a headline!
Stories with short headlines simply do better than stories with longer headlines.
With a portion of traffic coming from social media, concision matters. Headlines should contain as few extraneous words as possible but include a subject, an object and a verb.
Best practices about length change faster than fashion dictates hemlines, but generally: the shorter, the better.
Engaging: Headlines aren’t summaries of a story, they’re ads for it. You have a few seconds to pitch the reader into reading more. As such, good headlines promote the most exciting/interesting/new thing about a story. Identify the “wow!” aspect of your story, then back it up. This is your elevator pitch.
Active: Bad headlines are often extremely passive, or simply a statement of the topic. If you think of headlines as a summary, these often seem OK, but if you think of a headline as a pitch, it’s clear these are non-starters.
Examples:
“Welcome to the mind-bending world of cloud-on-cloud computing”
“Raising the bar for open source standards”
“Finding the right path for federated learning”
When you write headlines, ask yourself if they satisfy the three rules above. Is it a good pitch to a reader for clicking and reading more? Is the headline as concise as possible? Is it active? If it’s not, rewrite it.
If you have time, plug in a few of your key story terms (like confidential computing) to Google News to see how others in the industry headlined their work. You can also workshop with headline analyzers, but for “deep tech” subjects it’s often difficult to meet their parameters without sounding like a hysterical sales pitch, so a decent, accurate headline often scores low.
Never submit a story without at least trying to write a headline or two: It’s the mark of a writer who isn’t clear what their story is about. It’s fine to file with a few different options knowing the editor will play around with them. The editor’s job is to make you look good, but don’t force them to define your story for you – and possibly rewrite or reorganize it in the process.
Capitalization: Whether you follow the Associated Press, The Chicago Manual of Style, Microsoft or a house guide for headline styles, once you’ve settled on your hed, make it consistent. Nothing makes a publication look more slapdash than a home page, social or RSS feed with one headline in ALL CAPS followed by one styled in homage to bell hooks lowercase. The rougher your copy, the higher the likelihood that mistakes are published.
Depending on your content management system (CMS) it may be called something like “excerpt,” “teaser” or “intro.” It’s the short text published below the hed and before the main story. If you don’t fill it in, many platforms use the entire first paragraph— way too much text and a bad intro for the post.
This is where you persuade the reader (again!) to read the post. Add details that you can’t squeeze into the headline but that aren’t necessary in the lede or to tease a quote.
There are never links in these, for the same reason we don’t include them in the lede (see below.)
Dek examples:
“Algorithms struggle to understand human ambiguity. But such quirks are a flimsy shield against the threat of artificially intelligent hackers.”
“With the release of Lens 6 the underlying open source project was repurposed, breaking an unwritten rule.”
“If you’re running out of steam managing patchsets, comments and test environments, these tools can put you back on track.”
Similarly to the above, a good lede (aka the lead paragraph) is vital to enticing busy readers to spend more time on a post. Like a good headline, ledes should be short and engaging. However, a lede should be more than just a rehash of the hed or the dek: It should supplement it, flesh it out and offer an appealing hook to read more.
Short: Aim for a few direct sentences.
Avoid: links in the lede (or in the first sentence) unless you are pointing to an internal page. Otherwise, you’re pushing readers out of the story.
Example:
If the story is about a company, do not link to their homepage in the lede. Use the nut graf (see below) to link to a page germane to the story. If you’re writing about a company that the readers may not know, avoid cluttering the lede with an unfamiliar name. Same if your main source is a report - lead with the most important information, not the link to whoever provided it.
Lede examples:
“Some startups begin life in the family garage, but professor Christof Fezter’s home depends on a server in the basement from his latest venture for heat and hot water. Fetzer is one of three co-founders of Cloud&Heat GmbH, a startup based in Dresden, Germany, that aims to heat up the market for the green cloud.”
“Consider this web page you’re reading right now. The links, headers, and paragraph breaks are marked up with HTML. But Cascading Style Sheets (CSS) really define the look and feel of it: the colors, the fonts, the column widths, the placement of all the various boxes and elements. If you’re looking at this page on a mobile device, it’s CSS that makes it look right on a smaller screen.”
“Programming language Python is about 10 years younger than Kim Kardashian. In this case, age really does come before beauty. One is versatile, predictable and has earned growing popularity. The other, well, not consistently. Google searches for Python outstripped those for Kim Kardashian in the United States last year. (Though it’s worth noting perhaps that she rallied in popularity with those topless Instagram pics in January.)”
Make sure that your ledes are:
Engaging: Earlier, we described a headline as an elevator pitch, a Hollywood term used by screenwriters to capture the interest of a producer you meet in an elevator with just a quick sentence or two. Sticking with that analogy, a good lede is the producer holding the elevator door and giving you a few more seconds to grab her attention. You want to tell her something she hasn’t already heard and flesh out what you’ve already said with more information – and persuade her to hear more.
Meaningful: A good lede gives an accurate representation of what the entire post is about and what content a reader will find after the dek. If it doesn’t, rewrite.
Ledes should clearly convey the newest, most interesting information in your post.
Do not start with background information. Work relevant background information into a nut graf that provides context and gives an overview of why the story is important. Save minor details for later in the story. The inverted pyramid structure - sparked by use of the telegraph - still stands.
Bend these rules for a tutorial or explainer - always clearly state what problem the technology solves and what the user can do with it.
Tutorial example:
“Confidential computing is the protection of data in use by performing computation in a hardware-based Trusted Execution Environment (TEE). While in cloud native workloads data is typically protected in transit through networking encryption (i.e. TLS, VPN), and at rest (i.e. encrypted storage), confidential computing enables data protection in memory while processing. The confidential computing threat model aims at removing or reducing the ability for a cloud provider operator and other actors in the tenant’s domain to access code and data while being executed.”
All feature stories need a nut graf. Bonus points for working it into any post, however short.
The nut graf is generally a few paragraphs into the story; this is where you put the background information you cut from your hed and lede. Or, as editors say: “context, context, context!” This is where you work the relevant numbers, provide a larger picture, tell the backstory. This is your last chance to answer the question “Why should I care?” Make it good.
She went on to construct Kepler.gl, a tool that helps make “beautiful maps in like 10 seconds” — without any coding. Built using the deck.gl WebGL data visualization framework, the ride-sharing company recently open-sourced the geospatial toolbox that can be used with QGIS, Carto and Mapbox Studio. Given its origins, it’s easy to see why Kepler excels at large-scale visualizations centering on geolocations.
Python provides the backbone for YouTube, DropBox, Instagram, Reddit, plus organizations like CERN and NASA. Some 286,701 users have contributed 147,123 projects to the “cheese shop,” the nickname for the Python Package Index, a nod to Monty Python that runs through so much of the language.
Jargon watch
You may know your LBaaS from your VPNaaS, but never assume the reader does. The momentum from emerging tech comes from people new to it—don’t push them away with the acronym-of-the-nanosecond.
Generally: Spell out acronyms on first reference, especially those specific to the technology or community. A new reader shouldn’t wonder whether a PTL is a project technical lead or one of the other 58 meanings on acronymfinder.com. If you’re unsure which common acronyms can stand without explanation (e.g., NSA, CERN) check the AP (see link below.)
For the same reason, weed out business-writing cliches such as aha moment, mission critical, pull the trigger. They flatten your writing and are hard to parse for international readers. When in doubt, check http://unsuck-it.
Every publication needs one as a foundation. The AP Stylebook, updated for over 50 years, is a classic. A good, free starter guide: https://www.scribd.com/doc/2664713/Associated-Press-AP-Style-Guide-the-basics
For tech content, check out the Microsoft Style Guide.
A few small points worth making:
Second reference to a person is always last name. So for Roberta Smith, refer to her as “Smith” after the first reference, not Roberta. Unless you’re publishing the Scout Newsletter and writing about your 10-year-old pals, it’s too informal.
Job titles are capitalized only before a name and, since they tend to go after, that means almost never. The exceptions are common acronyms CEO, COO, CTO.
Time: Use figures except for noon and midnight. Use a colon to separate hours from minutes (e.g. 2:30 a.m.) For events, include time zone information (11:30 a.m. CET) and a link to a time zone converter: http://www.timeanddate.com/worldclock/meeting.html. Bonus points if you convince your organization/publication to use the 24-hour clock instead.
All stories need links, so please file your story with some.
You can include them in a list at the bottom of the story so that if multiple people are editing the document they don’t accidentally get deleted during the edit process.
Make sure the links point to useful information. They help you to write shorter - you can talk about statistics from a report without mentioning the whole thing or reference other stories in a series. If the highlighted portion for the link is a working breakfast session at a conference, links to that specific session or a write-up of the session – not the main conference page.
All stories should be filed with artwork - photos, images, graphics, social embeds. List some potential picks when you file. Treat the art as another way to communicate by adding information and punch to your story. Images often work best when witty or unexpected, riffing off the headline verb.
Example: Here’s how articles with headlines about “cloud computing myths debunked” have used art. Hands down, the paper unicorn on a laptop is the winner on social media.
Looking a these examples, it’s clear that you need something that looks good horizontally and, this is crucial, doesn’t have writing on it. (These images often go underneath the headline inside the story and extra writing reduces overall legibility.)
Find CC-licensed art on Creative Commons or Flickr and on sites with permissive licenses like morguefile.com and unsplash. Artificial intelligence is fun to play with too - just check the images carefully. Searching for “red pen editing” on umprompt pulls up a bunch of spooky gothic images, along with a hipster, sweating over a backward typewriter. (Same search on DuckDuckGo, for comparison.)
Written by Nicole Martinelli CC BY-SA First published on Superuser. Version 0.3