| A | B | C | D | E | F | G | H | I | J | K | L | M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
1 |  | Editing Guidelines & Codes | ||||||||||||||||||||||||
2 | Process Phase | A.1.1.1 | Category | Code | Principle | OSP Pillar | ||||||||||||||||||||
3 | A. Scope & Narrative Structure | A.1.1 | Opening | LEDE | Don't bury the lede. In the article, or even in a sentence. | Clarity | ||||||||||||||||||||
4 | A. Scope & Narrative Structure | A.1.2 | Opening | FRONT | Clearly identify your main point or idea up front, in the opening section. | Clarity | ||||||||||||||||||||
5 | A. Scope & Narrative Structure | A.1.3 | Opening | SPFIC | Make the scenario or problem space specific instead of vague, general claims. Address audience pain points. | Clarity, Trust | ||||||||||||||||||||
6 | A. Scope & Narrative Structure | A.1.4 | Opening | WHOM | Identify (explicitly or implicitly) your audience in the opening section. This is not a grammar issue, it is to help readers self-select and identify with a pice (or not). "Teams delivering client sites often ..." "Managing large number of servers ..." | Clarity | ||||||||||||||||||||
7 | A. Scope & Narrative Structure | A.1.5 | Opening | WIIFM | Lead with the benefit. Clearly show why the audience will care about the idea/thesis in the opening section. | Clarity | ||||||||||||||||||||
8 | A. Scope & Narrative Structure | A.3.1 | Logical Rigor | POINT | Points supporting an argument, thesis, or claim can be strong, weak, or missing. This is somewhat subjective! Editors, please expand on this when you use this code. | Clarity | ||||||||||||||||||||
9 | A. Scope & Narrative Structure | A.3.2 | Logical Rigor | SPOCK | Use clear, logical thinking. Avoid logical fallacies. Check that all evidence is directly connected with a cause/effect relationship to the claim. | Clarity | ||||||||||||||||||||
10 | A. Scope & Narrative Structure | A.3.3 | Logical Rigor | FACT | _Back all factual claims by evidence with examples, testimonials, statistics or other research. _Emotional claims are/can be acceptable without evidence, especially in a quote like a testimonial. _Include supporting points or information to add value to the narrative and/or thesis. | Trust | ||||||||||||||||||||
11 | A. Scope & Narrative Structure | A.4.1 | Closing | CTA | Close with a clear call to action. | Clarity | ||||||||||||||||||||
12 | A. Scope & Narrative Structure | A.4.2 | Closing | SUMM | Summarize your points/evidence and why it matters in the closing section. | Clarity | ||||||||||||||||||||
13 | A. Scope & Narrative Structure | A.4.3 | Closing | THESIS | Summarize your points/evidence and why it matters in the closing section. | Clarity | ||||||||||||||||||||
14 | B. Flow & Readability | B.1.1 | Flow | FLOW | Organize the sections and paragraphs in a logical order and ensure they have an elegant flow and transition to them. | Clarity | ||||||||||||||||||||
15 | B. Flow & Readability | B.1.2 | Flow | RHYTH | Be aware of the length of paragraphs, avoid overly long blocks of text. Stagger length. Create rhythm and visual variation for your reader. | Empathy | ||||||||||||||||||||
16 | B. Flow & Readability | B.2.2 | Structural Aids | SUBHD | Relevant subheads assist the reader by breaking up copy and defining the purpose of each text block. This is the structural perspective on the code HEAD. | |||||||||||||||||||||
17 | B. Flow & Readability | B.2.2 | Trust and evidence | EXMPL | Examples enhance the thesis or claims by helping to create a picture in the reader's mind. | Trust, Empathy | ||||||||||||||||||||
18 | B. Flow & Readability | B.2.3 | Trust and evidence | QUOTE | Quote your subject matter expert directly wherever possible to build trust, authority, and add interest. | Trust | ||||||||||||||||||||
19 | B. Flow & Readability | B.2.4 | Trust and evidence | TRUST | Where possible, mention or highlight signals of trust | Trust | ||||||||||||||||||||
20 | B. Flow & Readability | B.3.1 | Tight Writing | CASE | Make sure each point in each paragraph is valid, relevant, and unique. | Clarity, Trust | ||||||||||||||||||||
21 | B. Flow & Readability | B.3.2 | Tight Writing | CLUTT | Cut all clutter (no extraneous words, sentences, or paragraphs). If your words do not build the case toward the conclusion or your thesis, they are extraneous. Good writing is often a process of rewriting, and editing with a critical eye. Judge your writing as if someone else wrote it. | Clarity | ||||||||||||||||||||
22 | B. Flow & Readability | B.3.5 | Tight Writing | TOOM | Avoid over explaining or providing too much detail. Only explain what is relevant in the context of the article. | Clarity | ||||||||||||||||||||
23 | B. Flow & Readability | B.4.1 | Coherence & Readability | HEAD | Relevant subheads assist the reader by breaking up copy and defining the purpose of each text block. This is the readability perspective on the code HEAD. | Clarity | ||||||||||||||||||||
24 | B. Flow & Readability | B.4.2 | Coherence & Readability | LIST | Bulleted lists efficiently present information (usually, only once per article). This format is easily scannable and provides a visual break in the copy. | Clarity | ||||||||||||||||||||
25 | B. Flow & Sections | B.4.3 | Coherence & Readability | WALL | _ Use headers, paragraphs, blockquotes, and lists to add visual variation and interest. _ A wall of words will put off a reader at a glance. | Clarity | ||||||||||||||||||||
26 | B. Flow & Readability | B.4.6 | Coherence & Readability | ILLUS | _ Add non-text explanations, metaphors, and data using photos, charts, diagrams, or illustrations where possible. _ Images provide visual interest and a variation in long articles. _ A picture is worth 1000 words for conveying some kinds of information efficiently. | Clarity, Empathy | ||||||||||||||||||||
27 | B. Flow & Readability | C.1.? | Audience | SEP | Separation of concerns. Sometimes two different points are combined in a single sentence, and should be made separately. This can also apply to a paragraph, section of an article, or even an extraneous topic in one post that you can remove or break out into its own article. | Clarity | ||||||||||||||||||||
28 | C. Style & Phrasing | C.1.1 | Audience | CNECT | Use language that will connect with your target audience, but avoid jargon that will prevent non-experts from gaining value from your writing. | Empathy | ||||||||||||||||||||
29 | C. Style & Phrasing | C.1.5 | Phrasing | EMPATH | Write with the needs, problems, perspective of the target audience in mind | Empathy | ||||||||||||||||||||
30 | C. Style & Phrasing | C.1.9 | Grammar, Style and Phrasing | ANLGY | Use analogies to help make raw (dull) data more interesting and help people visualise it. e.g. "That's enough people to fill 2/3 of Yankee Stadium," "That's enough cable to go to the Moon and back 3 and a half times," "That's enough electricity to power the city of New York for a week." (see chap. 19 "Everybody Writes" Ann Handley where she says to us "common, but surprising" analogies) | Empathy, Clarity | ||||||||||||||||||||
31 | C. Style & Phrasing | C.2.1 | Tone | CRIT | Hidden or Implied Criticism Don’t tell people they’re "doing it wrong" ... Avoid telling the reader she is doing it wrong, or is weak, stupid, or inadequate. Externalise the problem away from the reader, "a common problem is", "a common mistake is." We can blame the software. We can suggest way to do something better, make your day better, improve efficiency. | Empathy | ||||||||||||||||||||
32 | C. Style & Phrasing | C.2.2 | Tone | BRAND | Match the tone to the brand guidelines on tone. | Empathy | ||||||||||||||||||||
33 | C. Style & Phrasing | C.2.3 | Tone | TONE | Match the tone for the right use case (eg. support versus marketing). Follow client voice guidelines where provided. | Empathy | ||||||||||||||||||||
34 | C. Style & Phrasing | C.2.4 | Tone | FUD | Avoid negative copy and FUD marketing (fear, uncertainty, doubt). We want to make a positive difference in the world. Highlighting the positive, the benefits or USPs a given product offers is far stronger and clearer in our opinion than resorting to criticizing the competition. | Empathy | ||||||||||||||||||||
35 | C. Style & Phrasing | C.2.5 | Trust and evidence | HYPER | Avoid hyperbole, exaggeration, binary comparisions (good/bad), and claims you can't back up. | Trust | ||||||||||||||||||||
36 | C. Style & Phrasing | C.2.6 | Tight Writing | CRISP | Write sentences that are spare and concise. Use occasional longer sentences to vary the rhythm of your writing. Aim for active voice, rhythm, and pace. Avoid flowery, long-winded words and sentences. Color is okay, but be mindful of the difference: “I would like to take this opportunity to extend my most hearty congratulations.” v “Congratulations.” | Clarity | ||||||||||||||||||||
37 | C. Style & Phrasing | C.2.7 | Tight Writing | REDUN | Avoid redundant words (e.g. future plans, unexpected surprise, most optimized) | Trust, Clarity | ||||||||||||||||||||
38 | C. Style & Phrasing | C.3.1 | Inclusive and human-centric language | INCL | Use inclusive lanaguage to make sure readers feel respected and welcomed. Avoid language that shows prejudice, bias, discrimination, or a lack of sensitivity. Balance use of she/her with he/him in texts. Our preference is for a majority to be she/her. All she/her may be often acceptable; all he/him may not be. "They" can also be acceptable. | Empathy | ||||||||||||||||||||
39 | C. Style & Phrasing | C.3.2 | Inclusive and human-centric language | JUDG | Non-violent language. Replace subjective evaluations or judgements with specific outcomes or needs. | Empathy | ||||||||||||||||||||
40 | C. Style & Phrasing | C.3.3 | Inclusive and human-centric language | PAX | Non-violent language. Aim to use non-violent language by replacing metaphors around war, sports, and sex, with other, more peaceful, constructive ones like art, carpentry, and gardening. | Empathy | ||||||||||||||||||||
41 | C. Style & Phrasing | C.3.4 | Inclusive and human-centric language | DIRCT | Use direct address when appropriate. e.g. replace "Many customers benefit from our product," with "You will benefit from our product." Make instructions simple and direct: replace "Please be aware that we can also make instructions simple and direct," with "Make instructions simeple and direct." | Empathy | ||||||||||||||||||||
42 | C. Style & Phrasing | C.4.1 | Accessibility | A11Y | Write for accessibility. We love The Stanford Online Accessibility Program guide on this. | Empathy | ||||||||||||||||||||
43 | C. Style & Phrasing | C.4.2 | Accessibility | SIMPL | Use simple language where possible. This is especially important for international audiences. | Clarity | ||||||||||||||||||||
44 | C. Style & Phrasing | C.5.1 | Phrasing | FEEL | Your sentences should create pictures, feelings, emotions for the reader. | Empathy | ||||||||||||||||||||
45 | C. Style & Phrasing | C.5.2 | Phrasing | DIR | Use the direct path to the explanation. Avoid longwinded paths to the point. | Clarity | ||||||||||||||||||||
46 | C. Style & Phrasing | C.5.3 | Phrasing | KISS | Avoid making points sound needlessly complicated | Clarity | ||||||||||||||||||||
47 | C. Style & Phrasing | C.5.4 | Phrasing | REPET | Avoid careless repetition | Clarity | ||||||||||||||||||||
48 | C. Style & Phrasing | C.5.6 | Phrasing | FRESH | Avoid cliches or stale expressions | Trust | ||||||||||||||||||||
49 | C. Style & Phrasing | C.5.7 | Phrasing | METPH | Be consistent if you use a metaphor. Try to carry it through the entire article and/or its logical conclusion. | Clarity | ||||||||||||||||||||
50 | C. Style & Phrasing | C.5.8 | Phrasing | COLOR | Color and energy. Choose interesting, exciting ways to express things—but not at the expense of clarity and allthe rest :-) | Empathy | ||||||||||||||||||||
51 | C. Style & Phrasing | C.5.9 | Phrasing | CLEAR | Clear writing. Avoid vague descriptions of benefits. Be as specific as possible. | Clarity | ||||||||||||||||||||
52 | D. Word choice | D.1.1 | Strong verbs | ACTIV | Use the active voice (mostly) to center the reader in the action. Check if gerund (-ing) phrases are weakening your message. | Empathy | ||||||||||||||||||||
53 | D. Word choice | D.1.2 | Strong verbs | VERBS | Replace common, weak or vague verbs with more specific, colorful ones. | Trust, Clarity | ||||||||||||||||||||
54 | D. Word choice | D.1.4 | Strong verbs | LEAD | Lead with verbs and actions | Clarity | ||||||||||||||||||||
55 | D. Word choice | D.1.5 | Strong verbs | TENSE | Tense. Check it’s in the right tense and consistent throughout. | Clarity | ||||||||||||||||||||
56 | D. Word choice | D.2.? | Accuracy & Terminology | AMBIG | Avoid ambiguity. Avoid being vague. Word choice can leave things open to interpretation. Be as specific as possible. | Clarity | ||||||||||||||||||||
57 | D. Word choice | D.2.1 | Accuracy & Terminology | TERM | Technical terms and technology names - Explain what they are, what they do to make sure your audience (at relevant levels of experience) are all on the same page with you. Define technical terms directly in the article. Link to other articles with deeper explanations, where it makes sense. Ensure technical accuracy (research, ask an expert, ask the client). Mistakes of this type can impact overall credibility of the content. | Trust, Clarity | ||||||||||||||||||||
58 | D. Word choice | D.2.3 | Accuracy & Terminology | BUZZ | Jargon and Buzzwords. Replace jargon, buzzwords, and clichés with a clear and concise statement that expresses your point. This can be expressions like "clear as a bell" or technical acronyms like "IEEE Std 802.11-2007" . The former lacks any specific information helpful to the reader, while the latter can prevent a reader who is not an expert in the field from understanding the copy. (ref: "Everybody Writes" Ann Handley) | Trust, Clarity | ||||||||||||||||||||
59 | D. Word choice | D.2.4 | Accuracy & Terminology | ACRO | Acronyms - explain what they stand for (what they are, what they do as needed) | Trust, Clarity | ||||||||||||||||||||
60 | D. Word choice | D.2.5 | Accuracy & Terminology | DATE | Stay current and relevant, don’t date your content. ("Last September," "earlier this year," etc.) | Clarity | ||||||||||||||||||||
61 | D. Word choice | D.2.6 | Accuracy & Terminology | ANTE | Be clear about what "this, "that", "they" refer to | Clarity | ||||||||||||||||||||
62 | D. Word choice | D.3.1 | Grammar and punctuation | GRAM | Check for grammar errors | Clarity | ||||||||||||||||||||
63 | D. Word choice | D.3.2 | Grammar and punctuation | MODIF | Put modifiers (words that alter others) in the correct order. | Clarity | ||||||||||||||||||||
64 | ||||||||||||||||||||||||||
65 | ||||||||||||||||||||||||||
66 | ||||||||||||||||||||||||||
67 | ||||||||||||||||||||||||||
68 | ||||||||||||||||||||||||||
69 | ||||||||||||||||||||||||||
70 | ||||||||||||||||||||||||||
71 | ||||||||||||||||||||||||||
72 | ||||||||||||||||||||||||||
73 | ||||||||||||||||||||||||||
74 | ||||||||||||||||||||||||||
75 | ||||||||||||||||||||||||||
76 | ||||||||||||||||||||||||||
77 | ||||||||||||||||||||||||||
78 | ||||||||||||||||||||||||||
79 | ||||||||||||||||||||||||||
80 | ||||||||||||||||||||||||||
81 | ||||||||||||||||||||||||||
82 | ||||||||||||||||||||||||||
83 | ||||||||||||||||||||||||||
84 | ||||||||||||||||||||||||||
85 | ||||||||||||||||||||||||||
86 | ||||||||||||||||||||||||||
87 | ||||||||||||||||||||||||||
88 | ||||||||||||||||||||||||||
89 | ||||||||||||||||||||||||||
90 | ||||||||||||||||||||||||||
91 | ||||||||||||||||||||||||||
92 | ||||||||||||||||||||||||||
93 | ||||||||||||||||||||||||||
94 | ||||||||||||||||||||||||||
95 | ||||||||||||||||||||||||||
96 | ||||||||||||||||||||||||||
97 | ||||||||||||||||||||||||||
98 | ||||||||||||||||||||||||||
99 | ||||||||||||||||||||||||||
100 |