Writing guidelines for contributors

Of writage

Awright, a primer on how people read online.

“Lazy, brutish and short” might be a good summary. The vast majority of people on the vast majority of sites do not actually read the site.

One picture is worth etc.:

This is an eyetracking heat map, so the “hot” parts are where the eyes of most people rest the longer (they are actually reading). Grey means that nobody spent significant time looking at these parts.

As you can see, people scan rapidly through pages — they don’t read from beginning to end. The number of people who will be reading past the third paragraph or so (assuming short paragraphs) is poor. Scrolling past the first screen is an imposition (only 20% of the reading effort is spent on stuff you have to scroll vertically to see).

Tests constantly have most people missing information that is *right here on the screen* because they can’t be arsed  to actually read.

On the average page, people will only read about 120 words.

Qualifiers

First, the majority of these studies take place on sites where people have come to take *action*. They want to buy things (that’s why we invented people in the first place, to buy things) if it’s a commercial site. Or they want to find stuff if it’s, say, a search engine. They want their prize now, and with the least possible effort.

You might think that it ceases to apply to, say, news sites and other online journalistic places. Actually it’s broadly the same. Newspapers websites chiefly offer newspaper articles, people have come to the newspaper site, and do they genuinely read the newspaper articles ? Noooooo.

There’s a reason so many outlets have these shitty “listicles” (list-based articles). It’s because that’s what most people want. Lists are the easiest format to scan, to speed-read. Most people are just vaguely killing time whilst pretending to work and/or sharing on social networks articles that’ll make them look good but they’ve not actually read.

Also, people in their late 30s and beyond often are so-so at reading on screens. And by your 40s, eyesight often has so-so contrast.

Therefore ?

Therefore it’s important not to frame Ian Hypothetical Reader as passionate and eager to learn come death or high water. It’s best to imagine that you’re writing for a tired, inattentive person.

Why ?

Because everybody benefits. People have a certain amount of “fuel” to spend on reading an article. If the road is smooth and straight they’ll go much further. Even with enthusiasts, the “fuel” can be limited by outside events, fatigue, anxiety, reading on a mobile device on a commuter train, etc.

Furthermore, making the road smooth is mostly about *looking* easy to read and low-effort. It’s not quite about the material itself (though good writing must be clear, obvs) than about presentation and good writing habits.

A lot of road-smoothing is already done by our layout, font, look-and-feel, etc.. But there’s work left with the text itself.

Core practices

So how do you make your material look like a smooth road ?

• Short sentences.
• Paragraphs that are only two or three sentences long.
• One idea per paragraph, even if that means one-sentence paragraphs.
• Copious headings and sub-headings (subheadings every three or four paragraphs often works).
• Banner images so it doesn’t look like a wall of text.
• Bullet-point lists whenever your paragraph is sort of, kind of, a list of things.
• Simple, direct, lean style.
• Concision, concision, concision.
• There is no “write”. There is rewrite, rewrite, rewrite.

Keep in mind that nearly half the audience is ESL . Keep in mind that the average American reading level is 7^th to 8^th grade (so roughly a 13-year-old).

Writing style discipline

It’s a form of exercising. Here are habits to acquire through practice :

• Use a spell checker (the Google Drive one and the Notepad++ one are good and free).
• Spend time with Hemingway  until you’ve learned from it and can do without. That’ll take a while.
• Your draft can probably be trimmed down by about 25%. Usual suspects :
  • Make sure that everything serves a precise purpose. If a sentence or clause serves no clear purpose, kill it. Frex – History section starting with a variant of “little is known about the past of Bob”. That’s empty calories. Fluff. Filler.
  • An idea only needs to be expressed twice if there’s been a lot of information since it was explained. When writing a draft it is very common to tell the same thing twice because you’re still structuring your thoughts.
  • Kill most hedging/filler words. Common suspects include “essentially”, “basically” and other weak qualifiers ending in -ally. In many cases adverbs bring nothing to the table.
  • Amplifying adjectives are often killable. If you write that something is very (foo), highly (foo), etc. it is possible that there is a stronger adjective you can use instead. Why be very intelligent when you can be brilliant.
  • Use specific verbs rather than common, generic ones with an additional clause. Why have something in common when you can share it.
  • You may realise at some point that a whole paragraph or an entire series of paragraphs is actually dispensable. Do not hesitate – kill it. Sometimes, the first draft just rambles. Kill the fluff.
• For what it’s worth, a common objective when prepping a text for professional online publication is not to trim by 25%. It’s to trim by 40%.
• Make about three passes over 10 days over your text. Considering your text with a fresh eye is the key to most improvements. There is no write. Only rewrite.
• Reading your text aloud is good at catching convoluted, overlong stuff.
• Constantly watch for sentences that are actually two sentences. The word “and” is suspect. It might be used to weld together two sentences that’d be better left alone (especially if it follows a comma). Ditto for semicolons and dashes.
• If you have somebody around who can give frank but informed feedback, that’s great.
• Ensure that most of your sentences are about a clearly-defined person conducting a clearly-defined action. Common traps include ambiguous pronouns, and using the passive voice where an alternative exists. Passive voice (“The dog was walked by Bob”) is usually the wrong choice.
• It’s fine to have a neutral, bland style. You’ll get to be quirky and personable once you’ve truly mastered the basics, in about 80 years.
• When referring to a generic person use the singular they rather than a pronoun of an arbitrary gender or the clumsy “he or she”. The singular they was good enough for Shakespeare.
• Exact names of ships and books in italics, and proper diacritics on foreign words where applicable. This makes the text look less monotonous, and it makes you look suave and worldly.
• Numbers are usually more efficient in numerical form. For instance “18” reads much better than “eighteen”, and “40” requires less effort to understand than “forty”. A good rule of thumb is “ten or less in letters, 11 or more in numbers”.
• Rewrite, rewrite, rewrite.
• If there’s a lot of background to explain to make a plot point comprehensible, consider two alternative strategies :
  • If it’s not that important or interesting, just elide. ”An arbitration using local laws” is bland, but it may be a better choice than a complicated explanation about what actually happened and what the rules were.
  • If it’s important, consider writing a separate section, sub-section or boxed section explaining the context rather than cramming it into the narration itself.
    This is especially true if a complex concept is necessary at several points. If understanding what the Red Room is is critical at several points, have a separate section explaining it once and for all at the beginning. This way the reader has the tools when reading the History section.
• Concision, concision, concision.
• If a text includes spoilers, clearly signal S P O I L E R S in the Reasons part of the entry’s header.
• If some bit is not clearly stated in the story, *always* frame it clearly as a hypothesis, a No-Prize Hypothesis(gloss), your own guess, etc.. In many cases it is also worthwhile to note it when some info comes from a secondary or tertiary source.
• Revisit your old published texts with the benefit of a fresh eye and improved skills and experience. Yeah, I know that few people want to trudge through this, but it is efficient for self-improvement. And it’s the most efficient way to improve the average quality of the site.
• Collect illustrations and list recommended stories as you work so you don’t have to do it later. Keep illustrations in native TIFF format, and shared on Google Drive.
• Vivid examples are almost always good… unless your text already looks too long.
• Explain things in non-DCH (or DCA) terms. That way you can place it outside of the game stats section, for all readers. Howbeit, since the names of Powers, Skills, etc. in DCH are plain English, you can pepper explanations with these terms.
  Frex, the sentence “she can emit plasma beams (Energy Blast)” doesn’t look too strange to the layman. Even better, have the first occurrence be “she can emit plasma beams (in DC Heroes terms, Energy Blast)”.
• Don’t Randomly capitalise Things. Especially since we use capitalisation to distinguish terms of art from their normal use (power vs. Power, equipment vs. Equipment, etc.).
• “Linking words” are a great tool to keep things lean yet coherent-sounding.
  • Typical “logical continuity” linking words : Furthermore, for instance, moreover, thus, accordingly, consequently, likewise.
  • Typical “logical opposition” words : However, despite this, nevertheless, nonetheless, still, although — and I like to occasionally throw a “howbeit” here in there for fun.
• These linkers are best used at the beginning of the sentence, as a tell. ”Carlos refused to comply, however, and activated the rocket” is a tad weak. For starters, “however” is not needed in the middle of this specific sentence, since we already know that Carlos refused to comply.
  “However, Carlos refused to comply and activated the rocket” provides better guidance and IMO has a better rhythm. It tells the reader something unexpected is about to happen, marks a dramatic beat, then states the facts without interrupting the action to throw in a qualifier.
• To keep the History sections short, an important question is “yeah, but was this stuff important for the character ?”. The entry is a character profile, not a sprawling plot summary. Verrry complicated events often have very little impact on the character.
  If Bob was just a face in the crowd during X-Men: Schism, something brief (“when the mutant community split over ideological reasons, Bob chose to follow Forbush Man”) will suffice. One of my personal triumphs was “Drax was involved in the Infinity Gauntlet, Infinity War and Infinity Crusade events but didn’t understand any of it” then shamelessly moving on.

Cleaving

A lot of the readability/UX work on writeups.org since the late 2000s has been about cleaving.

Cleaving overlong sentences. Cleaving overlong paragraphs. Sub-section titles and banner images to cleave walls of text. ”Base camp” articles to excise repetitive, complex content from individual profiles. Even m-spaces to add a cleft between sentences.

Another big thing has been splitting articles into smaller articles. It’s not always possible but we’ve done a lot of that – usually taking the opportunity to rewrite because rewrite, rewrite, rewrite.

As it happens, some research on medium.com  indicates that an “ideal” post length is about 1,500 words (or maybe 2,000, depending upon their successive estimates), which corresponds to 7 minutes for a median reader.

Is it a good target ? Prolly not, because what we do falls more under the “longread” or “longform” journalistic format. But let’s explore that further.

Words count – need for speed

First, let’s have some stock reading speeds in wpm (words per minute). I have my doubts about these numbers, but they provide a rough idea and that’s our goal here.

3rd grade students 150
4th Grade Students 170
8th Grade Students 250
11th Grade Students 350
Average Adults 300
Low Scoring College Students 340
Average College Students 450
High Scoring College Students 800
Mid Level Executives 340
High Level Executives 575
College Professors 680
High School Dropouts 240

FWIW Medium.com assumes 275 wpm for its readers, which doesn’t seem absurd especially when you count ESL readers or people reading on the go. It’s not uncommon to set the bar of “long reads”… at 1,500 words. Which is something I’d clear well within two minutes, personally.

A typical press article is 300 to 500 words, because experience shows that people skip longer articles. Past 2,000 words, you *are* asking for a level of effort that is significant for many readers.

Words count – it’s over 3,000 !

Based on these estimates, practices in longread journalism, the site’s goal and our layout, an okay target for us would be :

• 3,000 words per article if there are no stats (usually meaning a “base camp” article).
• Between 4,000 and 4,500 words for a character profile with a meaty stats section.

It doesn’t mean you absolutely have to shoehorn any given article under this size. The original question was more about breaking overlong articles into smaller parts.

But keep in mind that a 4,300-ish words character profile (including the stats) is a 15mn read for a 275wpm reader, which is a significant ask. And it’s assuming that they do not spend time analysing the statistics (or looking at the pictures, for that matter).

So to earn the right to inflict articles that long on an unsuspecting populace, I think it’s only fair that we keep working on the readability, concision and style of our prose.

Tiny rewriting example

This entry had just two paragraphs of text :

Glommers are some sort of gigantic amphibian-like creature with a huge mount, clawed reptilian arms, a tail and no back legs. They are reportedly native to Apokolips’ underground caverns, where they eat mutated mosses and fishes then sleep as they digest their meal.

The Glommer encountered by Superman pounced on the surprised Man of Steel, swallowing his head in its mouth and wrapping its tail around his body. Within the mouth some sort of psychic effect was active, which tapped into Superman’s nervous system. Unable to see, hear or smell (since his head was inside the Glommer’s maw), Superman was also essentially paralysed by a seizure as his muscles spasmed – and the effect also involuntarily triggered his power of flight, sending him and the Glommer right into a Fire-pit.

Issues with my first paragraph :

• “Some sort” is useless, especially since there’s the modifier “-like” after amphibian to note the alien quality of the creature.
• Typo – “mount” for “mouth”. And “rear legs” would prolly be clearer.
• “Underground caverns” is arguably redundant ; “networks of caverns” says the same thing with more and more visual information.
• The second sentence may have too much information crammed in, consider two sentences instead. Also, “digest their meal” is redundant, especially since I’ve just stated what they eat !
• A ruthless editor would kill the clause about digestion as pointless details. However, as I see it the goal of WORG is to provide folks with this sort of detail to faithfully feature the creature in a game, so it stays.

Issues with my second paragraph :

• The first sentence is a bit clumsy because it signals that only one Glommer was ever seen. Is this information worth the clumsiness ? I’m now inclined toward ’no’ ; a separate short sentence would be clearer and avoid the clumsy.
• “Within the mouth […] was active” is a strange bit of effort to make the sentence more intricate and passive than it needs. And the “some sort” clause is not necessary at all, just pointlessly making things vaguer.
• That his head being in the beast’s mouth would block his senses is… kinda obvious. I see what I meant to explain, but readers are not that dumb. That I felt the need to have a parenthetical explanation is a good sign that I’ve botched my sentence.
• Plus, generally speaking, when you swallow something it’s, y‘know, with the mouth. Usually. Also the Glommer didn’t “swallow” his head, though I don’t think there’s just the right word to take something in your mouth and vaguely try to eat it but mostly focus on emitting an oral psychic field.
• Use of “essentially” is also a red flag ; furthermore the same thing is explained twice as paralysis and then as a seizure. Redundant.
• The last sentence has three distinct events, that’s one too many.

Fixes before publication :

Glommers are gigantic amphibian-like creature with a huge mouth, clawed reptilian arms, a tail and no rear legs. They are reportedly native to Apokolips’ networks of caverns, where they eat mutated mosses and fishes. They then sleep as they digest.

Only one Glommer was ever seen. It pounced on the surprised Superman, gobbling his head and wrapping its tail around his body. A psychic field within the Glommer’s mouth then induced a seizure in the Man of Steel – which involuntarily triggered his power of flight.

Paralysed and with his head still within the creature’s maw, Superman crashed right into one of Apokolips’ Fire-Pits.