Style Guide

Here are some guidelines to follow when writing for Superuser. 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: since they are flagged by spell check, they’re unlikely to get published by accident.

The three rules of good headlines

  •  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 as a rule. With a large portion of traffic coming from social media, concision is more important than ever. Headlines should contain as few extraneous words as possible and be less than 90 characters long. (e.g. “Take these OpenStack Infrastructure tools and run!”)
    • Engaging – Headlines aren’t summaries of a story, they’re ads for it. You have a few seconds to elevator pitch the reader into reading more. As such, good headlines promote the most exciting thing about a story. Identify the “wow!” aspect of your story, then promote it.
    • Active – Bad headlines are often extremely passive, or report the status quo. If you think of headlines as a summary, often these seem OK, but once you start thinking of a headline as a pitch, it becomes clear these headlines are non-starters.

Examples:

  • “Welcome to the mind-bending world of cloud-on-cloud computing”
  • “OpenStack moves from inflection point to business as usual”
  • “OpenStack wins hype cycle”
  • “The secret history of OpenStack, the free cloud software that’s changing everything”

When you write headlines for Superuser, ask yourself if it satisfies the three rules above. Is it a good pitch to a reader for clicking on the headline and reading more? Is the headline as concise as possible? Is it active? If it’s not any of the above, rewrite it. Where possible, jump into Slack to workshop it.

Capitalization: once you’ve settled on your hed, capitalize the first word and proper nouns, not every word. 

How to write a good dek

In our current CMS this is called an “Excerpt.” It’s published below the hed and before the main story.  If you don’t fill it in, WordPress uses the entire lede—that’s way too much as well as a bad intro to the post. You’ll find the Excerpt field at the very bottom of the post, below Yoast.

This is where you persuade the reader (again!) to read the whole thing. You can 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.)

Examples: 

  • “We’ve seen OpenStack customers growing faster than our overall business.” –Pat Gelsinger, CEO of VMware   
  • If you’re running out of steam managing patchsets, comments and test environments, these open source tools developed by OpenStack can put you back on track.

Don’t see the box? Scroll all the way up for a tab called “screen options.” Use the down arrow to open and make sure you have the “Excerpt” box checked

Ledes

Similarly to the above, a good lede (aka the lead paragraph) is vital to enticing front-page 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 instead supplement it, flesh it out and offer an enticing hook to encourage readers to read more.

  • Short – Aim for a few direct sentences.
  • Avoid links in the lede, unless you are pointing to an internal page of ours or openstack.org. Otherwise, you’re just pushing people out of the story. 

Example: 

  • This is acceptable: “If you’ve been to the OpenStack Documentation site recently, you may have noticed a new look.”

If the story is about a company, definitely 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 will not have heard of, avoid cluttering the lede with an unfamiliar name. 

Example: 

  • 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.

Make sure that your ledes are:

  • Engaging – Earlier, we described a headline as an elevator pitch, a Hollywood term used by screenwriters to describe capturing the interest of a producer you meet in an elevator with just a quick sentence. 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, but you also want to entice her into giving you a longer meeting.
  • Meaningful – A good lede gives an accurate representation of what the entire post is about and what content a reader will find after the jump. 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 less-important details for later in the story.

Nut graf 

All Superuser feature stories should have 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 may be your last chance to answer the question “Why should I care?” So make it good.

Examples: 

  • Pet Adoptions by Overstock is a free nation-wide public service that launched in March 2014 as a way to connect people to rescue animals. So far, it has forged over 28,000 connections between pets and potential owners who come to pets.overstock.com from a tab on the main page. The pets site is part of Overstock’s community-involvement initiative which includes the company’s other social responsibility efforts such as Worldstock Fair Trade, Main Street Revolution and Farmers Market.
  • OpenStack is software anyone can use to build their own version of Amazon’s Elastic Compute Cloud, the massively popular web service that gives developers and businesses instant access to virtual servers. The roots of OpenStack stretch back only about four years to a skunk works project inside of NASA, but it has already overturned the status quo in both the private sector and the public. After it was launched to the rest of the world through an unlikely partnership between the space agency and Rackspace — the Texas outfit that trails only Amazon in the cloud computing game — it’s now backed by over 150 companies worldwide. And it’s shaping the future of such names as HP, Cisco, Dell, and — if the rumors are true — IBM.

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 software or community. A new reader shouldn’t wonder whether a PTL is a project technical lead or one of the other 55 meanings on acronymfinder.com. If you’re unsure which common acronyms can stand without explanation (e.g., NSA, CERN) check the Associated Press (AP) (see link below.)

For the same reason, weed out the business-writing cliches;  for our international readers, those cliches are hard to parse. When in doubt, check http://unsuck-it.com.

Nuts & bolts of Superuser style

This is the niggly copy editor stuff where consistency is its own virtue. Superuser follows AP Style for things like writing numbers, names, datelines, commas (spoiler alert: no Oxford comma), etc. 

A good, free starter guide: https://www.scribd.com/doc/2664713/Associated-Press-AP-Style-Guide-the-basics

Some common style issues for Superuser: 

  • We are lucky to have a wide community of global contributors. If the writer is using English as a second language, go through every.single.line for subject/object/verb agreement and issues like capitalization/punctuation. More on this in the dedicated section below.
  • Second reference for a person is always last name. So for Roberta Smith, refer to her as “Smith” after the first reference, not Roberta.
  • 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. (Example: OpenStack COO Mark Collier. Also acceptable: Mark Collier, OpenStack COO, says TK.)
  • Time: Use figures except for noon and midnight. Use a colon to separate hours from minutes (e.g. 2:30 a.m.) Include time zone information (11:30 a.m. CET) and a link to a time zone converter – http://www.timeanddate.com/worldclock/meeting.html – so our global readers can participate.

Links

All Superuser stories need links, so please file your story with some.

If you’re drafting on Google Docs, 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. 

Make sure the links point to information that is useful. If the highlighted portion for the link is OpenStack working breakfast session in Paris make sure it links to that session or a write-up of the session and not the general Paris Summit page. 

Art

All stories should be filed with artwork. List some potential picks for art as links at the bottom. Treat the art as another way to add information or punch to your story. For example, “Three cloud computing myths debunked” has a picture of a paper unicorn on a laptop that got people commenting on social media.

For the cover photo, find something that looks good horizontally, has a subject that is well-centered (ideally sized 1024×768), and, this is crucial, doesn’t have writing on it. (The cover photos go underneath the headline inside the story and extra writing makes everything hard to read.)

Find CC-licensed photos using advanced search on Flickr or morguefile.com.

If you’re filing in WordPress, attribute the photos at the bottom of the story like this, making sure you’re in the “text” view (upper right tab):

<a href=”https://www.flickr.com/photos/clement127/16943072576/“”> Photo</a> // CC <a href=”https://creativecommons.org/licenses/by-nc/2.0/”>BY NC</a>

To upload, click on Featured Image on the right sidebar, then upload from your computer. When you look at the post in “Preview” mode, you’ll see what it will look like inside the story and can check for any weird sizing issues.

“Figures” are images inside the body of the story. Upload these by hitting that button at the bottom of the post and uploading them. Sizes on these can vary, but in general stick to 640×480. NB: these will upload where you have left the cursor in the story.  The code looks like this: ![alt text here](superuser:figure:vidmisrshgryv5kliklo)

You can move these pics around from the body of the story by cutting and pasting, but you cannot change the order of them from the button. There is no image library, so you can’t see them from there if you need to. 

Pre-publication checklist

Before you consider the post ready for editing, check the following:

  • The right-hand column on WordPress contains almost all of the necessary window dressing options. Save all of the changes you make by clicking “Save Draft” top right. The options are listed here in the order you scroll down the page—the most important ones are “featured image” and “excerpt” followed by “categories” and “tags.”
  • Categories
    • Tick the box for the story. The most common ones are “news” and “tutorial.” We use “featured” rarely because it banners that story across the whole top of the screen. Ticking the wrong category is still better than not ticking any box, because it will automatically chose “uncategorized” which leaves the post in limbo.
  • Tags
    • Add these using the main topics or company names for your post. You can almost never use too many, not using any will make your post harder to find for users. Examples: Open Infrastructure Foundation, open source community, Ceph, 5G, edge computing.
  • Featured Image
    • This is your cover image, see guidelines above. There is no default image. If you forget it, the story will publish (and tweet) with the headline over blank white space.
  • Snippet
    • Leave this blank.
  • Excerpt (aka Dek.)
    • Scroll down to fill this section with a sentence that describes more of what the post is about. This is published below the hed and before the main story (see main guide above for details.)  If you don’t fill it in, WordPress uses the entire lede, which is too long and repetitive as well as a bad intro to the post. You’ll find the Excerpt field at the very bottom of the post, below Yoast.  It’ll look like this when you preview:

Once you’ve made all these changes, scroll up to “Save Draft.”  Let the editor know that the post is ready to edit and any preferred publication dates or deadlines.

Written by Nicole Martinelli
CC BY-SA