The OSP Writing and Editing Guide

Who we are and how we write.

About Us

OSP bridges the tech-business gap, translates complexity to business value, and helps high-value organizations communicate effectively. Our Authentic Communication Framework encompasses our guiding principles. Read more about our principles, team, and manifesto.

This Guide is for You

This guide is for OSP team members and anyone who wants to learn how we work. We created structures, workflows, and processes to help us communicate authentically — on behalf of our clients and ourselves. This guide is a living reference to help us work together, use, improve OSP’s methodologies, and help others.

Our Values: Empathy, Clarity, Trust

We see that it is hard for many companies to produce content, especially around technical products and services, that is both compelling to read and technically accurate. 

The OSP Authentic Communication Framework helps us apply empathy, clarity, and trust in all communication work we do, creating strategically relevant content that is both compelling to consume and technically accurate, to connect our clients with those who need to hear their stories.  

Authentic Communication is a foundational principle of OSP. It operates both philosophically and operationally: permeating our culture and how we treat each other; as well as in the practical guidelines we follow, and the content we create.  

• We apply empathy by asking questions and using language that resonates with our audience. We put ourselves in readers’ shoes and understand their needs. 
• We try to be clear by producing technically accurate, logically rigorous, well-structured, and easily readable content.
• Writing that is logical, clear, and reflects an understanding of our readers goes a long way towards building trust. Furthermore, we work to earn that trust by avoiding jargon and being honest about what a given product can or cannot do.

Authentic Communication

Authentic Communication is a framework that applies empathy, clarity, and trust to create strategically relevant content that is compelling to consume and technically accurate.

Empathy 

It is important to understand the needs of your target audience to create content that is meaningful and relevant to them. 

In your content, show your audience—developers, marketers, whomever—that you understand the challenges they face in their day. This helps them identify themselves with the protagonist of the story, for example, in a case study. It also helps you write more credibly about the features and benefits of a given solution, showing them that it can resolve a common issue, reduce friction, or improve their work.

Active listening

Ask questions, listen, and seek to understand. Conduct interviews or surveys, or be present where your audience likes to be, such as Slack channels, GitHub, and Twitter.

Ask, listen, ask again … Never be ashamed to ask a question. Don’t be embarrassed if you don’t know a term or technology. Ask! Most subject-matter experts love talking about their area of expertise.

Language choice

Choose the language that takes your audience’s perspective, experience, and vocabulary into account. In content aimed at a developer audience, for example, talk to developers as another developer would. In your research, look up relevant questions or concerns a developer might express concerning your topic. 

Empathetic writing: an example

You run a survey and a common developer answer is something like: 

“My job is to develop solutions, but I spend only 10 percent of my time actually doing that, and 90 percent doing maintenance.” 

You might write: 

“As a developer, you probably get frustrated because you want to spend your workday developing new features, but instead, you find yourself bogged down with system maintenance. The solutions outlined in this article are aimed at minimizing maintenance issues, letting you get back to your job: developing new solutions.”

Clarity 

Technology can be complicated and abstract. Clarity is critical for an audience to understand the value of a product or service. 

Different vendors and communities often use different names and terms for the same concepts. Developers and business people have whole worlds of jargon they use that are obscure to the uninitiated. 

But clarity isn’t just about language, it is also embodied in the broader structure of your content and how it is visually presented.

To achieve clarity, be mindful of the following:

• Technical accuracy. (Leverage the knowledge of subject-matter experts.)
• Logical rigor and clear narrative structures.
• Tight writing: Crisp, sharp, focused.
• Compelling and accurate language.
• Scannable formatting, descriptive headers, and visual aids such as bulleted lists and callout quotes.

Trust

When you focus on empathy and clarity—especially in the form of technical accuracy and logical rigor—you will establish trust with your audience. 

Trust plays an important role in values-based decision-making. People make many of their decisions based on values rather than pure economics. This includes decisions about what they purchase from whom, and what tools and services they use. 

Two key ways you can establish trust with your audience when you’re writing:

• Make mindful claims. Avoid binary claims (like good/bad) or absolute claims (best/worst). Respect the nuance and situations where your product may not be the best.
• Back up your claims with quantitative and qualitative evidence. Use statistics or quotes from experts. 

Read more on OSP.com: Ten Ways to Build Better Communications with Trust

Writing Principles & Guidelines

Narrative structure and logical rigor 

Before writing pieces of content, we create a draft of their narrative structure. This narrative structure, or outline, determines the flow of content and allows writers and editors to check for clarity and logical rigor.

Logical rigor is an evidence-based approach to building an argument. Once you have a narrative structure, you can write with focus and attention to the logic of your argument. A narrative structure also allows editors to review an article’s structure and flow.  

Developing a thesis

Most narrative structures begin with the statement of the thesis. A thesis statement is the central message, argument, or main idea of a piece of writing, distilled into one or two sentences. 

State your thesis clearly in your introduction to establish your position and give your reader a sense of direction. To write a thesis: 

• Be Specific: Your thesis statement should be as clear and specific as possible. 
  • Before: CMSs have made some progress in recent years.
  • After: CMS tools for content editors have advanced in both functionality and ease of use in the past 5 years.
• Define boundaries: Your thesis should be limited to what can be accomplished in the planned length of the article.
• Take a nuanced position: Beyond announcing the article’s topic, your thesis should have a clear perspective on the matter. Have a strong opinion, without making universal or pro/con judgments that oversimplify complex issues.
  • Before: Open source CMSs are better than proprietary CMSs.
  • After: Both open source and proprietary CMSs have advantages, but open source CMSs can continually deliver significant new features because they are not subject to proprietary constraints. 

Tip: Your thesis will likely change as you revise and develop your ideas. Start with a tentative thesis and revise it as your article develops.

Common Narrative Structure

We’ll consider an article as an example—though most of the principles are universal across various types of assets. This narrative structure will cover about 80% of the pieces we write for OSP. All sections should include the following:

• Specificity: Specific scenarios or problem spaces are far more compelling than vague or general claims. Your writing should strive to be as specific as possible, 
• Audience: Have you identified your audience? (developers, business people, CTO’s, etc.) Is this article relevant to the intended reader? If not, revisit your basic premise. While you might not refer to them explicitly, your language, technical depth, and focus should be tailored to an audience. 

Opening Section 

Your introduction should provide a roadmap for the rest of your piece and provide context to your readers. Your introduction is crucial for the success of your article. It helps your audience determine whether your article is for them, and worth their time. 

• Introduction: Are you providing a compelling entryway into your subject? Are you guiding your reader towards the thesis?
• Thesis: What is your main point or idea?  This should be explicitly stated near the end of your introductory paragraph. 
• Purpose: Implicitly, you should be able to answer the reader’s question: Why should I care?

Middle Sections

In these sections, you’re making claims that support your original thesis. Each claim should build on the prior one, and be supported by evidence. Sometimes you will want to include counterclaims to more thoroughly explore a given topic, but it varies from piece to piece. 

• Ordering: Are the sections and paragraphs in a logical order? 
• Smooth Transitions: Do the transitions between paragraphs effectively link each paragraph to the next and all connect back to the main idea? 
  • Think about your continuity and transition between paragraphs.
  • Refer back to what you stated earlier to show the progression of thought. 
  • Series and lists can be helpful to the reader. 
• Evidence & Support: 
  • Does each paragraph contribute to the main idea?  
  • Is each point in each paragraph factual, relevant, and unique (non-repetitive)?
  • Is evidence used to prove points? Evidence might include:
    • Examples
    • Testimonials or direct quotes
    • Statistics or other research.

Concluding Section 

Your concluding section should restate the main idea, and leave your reader with an idea of what to do next. 

• Summary: Summarize your evidence and why it matters.
• Restated thesis:  Restate the thesis (main idea), though not verbatim. 
• Call to Action: Include a clear call to action that guides your reader to your 

Logical Rigor

So long as you’re using evidence-based claims to support your main argument, you’re employing logical rigor. Reference Purdue’s list of common Logical Fallacies to make sure you’re not falling into common traps, like overgeneralizations (e.g., open-source CMSs always make more sense than proprietary ones) or lazy straw man arguments. 

Flow and Readability

Headings

Use headings to visually organize your work. Relevant headings assist the reader by breaking up text and defining the purpose of each text block. They define the hierarchy of each paragraph within your piece of writing. 

Using important, key terms or phrases in headings and subheads can improve SEO and help search engines accurately interpret the intent of your content.

Lists

We use bulleted lists to make information more “visually digestible” for readers. When reading online, people scan for the information that interests them. Pulling information out of prose into bullets can help a reader find what they want faster. Use bullets when you have a list of three or more points.

We punctuate bulleted lists according to the Lists section of Google’s developer documentation style guide. 

We often use bulleted lists that resemble key-value pairs. The “key” is the main concept of that list item, as either a keyword or a statement, and the “value” is an explanation or justification. The key is set in bold and followed by a colon; the first word of the value is capitalized. This helps us not bury the lede and increases visual clarity. Where possible, use similar formulations for every key on the list.

For example:

• Something important: Now I am backing that up somehow.

When the beginning of the sentence needs to be emphasized, bold only the first key terms:

• Something important starts off my sentence and I keep going naturally.

Vary paragraph and sentence length 

Avoid overly long blocks of text. Sentences and paragraphs of different lengths provide visual variation and help your reader consume the information more easily. 

Visual aids

Use (relevant!) photos or illustrations where possible and appropriate. They help provide visual interest and relief in long articles. 

Use charts, callouts, blockquotes, and display quotes where possible to highlight or convey information efficiently and to provide visual interest.

Style & Phrasing

Make each word count

As writer Frank Conroy once said, “The goal isn’t brevity for its own sake but clarity.” You don’t have limitless space. Make your words count. 

Don’t use ten words if you can use five. “That” can generally be cut. Sometimes “With” or “of” can, too. Look out for filler terms like “at your fingertips” and cliche tech terms, like “disruptive,”

• Before: TYPO3 puts the support, flexibility, and features you need at your fingertips so you can start high-value projects quickly.  
• After: Launch projects quickly with TYPO3’s flexible, feature-rich Core and 24/7 support.

• Before: TYPO3 is a CMS that has a developer focus
• After: TYPO3 is a developer-focused CMS 

Go light on adjectives. As a general rule: verb > noun > adjective. Verbs and nouns describe without going overboard. 

• Before: TYPO3’s streamlined, efficient, disruptive CMS is great and easy for busy, hard-working content editors. 
• After: TYPO3 CMS’s workflows and editing tools save content editors time. 

Use active verbs often

Replace passive verbs with active verbs to clarify actions and meanings. Look out for “are”, “was”, “be” verbs followed by a past participle ending in -ed. 

Tip: Recognize passive constructions. They usually fail to mention “who” is acting. 

• Before: A content element can be moved, copied for reuse, and deleted. 
• After: You can copy, reuse, move, and delete content elements. 

• Before: Once our solution was implemented ...
• After: Once we implemented the solution ... 

Gerunds. Check if gerunds (phrases that end in -ing) are weakening your message.

• Before: “Creating an adequate content strategy template is a helpful tool for planning your content.”
• After: Create a content strategy template to plan your content. 

Replace helper verbs with more precise, active verbs. Look for “Has”, “does”, “gives”, “stay”, or “keeps” + a noun for candidates. 

• Before: “TYPO3 gives marketers the tools they need to keep simplifying the many decisions they have to make on a daily basis.”
• After: TYPO3’s tools simplify your marketing team’s daily decisions.

Bonus tip: This is an English-language thing. While we frown on passive constructions in English, they are perfectly acceptable in many other languages. Keep this in mind when you’re dealing with non-native authors or clients, or working materials translated from another language.

Be Specific

Use the most specific version of a word or phrase. Don’t generalize or be vague. Write about the technology or product at hand, rather than tech writ large.

Highlight words unique to product, company, or persona.  If reading something in isolation, could it apply to any or many technologies? If yes, try to make it more specific to your subject.

• Before: TYPO3 CMS was designed to support enterprises with the effective tools, systems, and frameworks that they need. 
• After: TYPO3 CMS supports enterprises with a User Access Management system, 24/7 support teams, and centralized Digital Asset Management. 

Watch out for filler words used in tech-speak, like “efficient”, “streamlined. ” Replace them with more specific, results-based phrases like “speeds up deployment” or “saves editors time.”

• Before: Get streamlined workflows that are customizable for editors’ and publishers’ needs. 
• After: Customize workflows to match your internal editing and approval process.

Write professionally and clearly

Grammar, spelling, style, and tone should be professional and correct. Generally, you should try to adapt tone and style to the right context or channel.  (It helps if the client has a Voice and Tone Guide done by OSP, of course!)

Avoid overly casual language that sounds more conversational than written. 

• Before: TYPO3 makes really great stuff for developer-type people.  
• After: TYPO3 is made for developers. 

But don’t be too stuffy… our friendly, open personality should still shine through.

• Before:  Review testimonies from our satisfied customers.
• After: Hear from our satisfied customers. 

Be positive. Rather than criticize competitors, frame the challenges our client is trying to solve—and highlight how they do it well. (OSP doesn’t do FUD or negative copy.)

• Before: Many content management systems come with a high risk of security vulnerabilities. TYPO3 keeps your installation protected with advanced security practices upheld by a dedicated team, and a great developer experience, and a community of 500+ contributors to boot.
• After: Keeping your website secure should always be top of mind. TYPO3 has industry-beating low numbers of vulnerabilities, maintained by a dedicated security team.

Be Compelling

Use words, verbs, rhythm, and sounds that resonate. This especially applies to taglines and headings.

Use interesting, bright verbs and nouns. OneLook Thesaurus is a great resource. 

• Before: TYPO3 helps agencies create digital value. 
• After: Agencies thrive when they use TYPO3.

Write headlines that grab attention. Try alliterations, varying rhythm, metaphors, etc. 

• Example Article Header Before:
  • The Open Social feature set focuses on community
• Example Article Headers After:
  • Community-Focused Features: The Open Social story
  • The (funded) future of Open Social

When stuck, look for ideas from around the web. Feel free to borrow sentence structures from well-known brands. 

• Example from Mailchimp: “Marketing smarts for big ideas.”
• Similar sentence structure:  “Security software for peace of mind.“

When in doubt, say words aloud to nail the right rhythms.

• Before: Our CMS is secure, scalable, and fast.
• After:  Our CMS is fast, secure, and scalable.

Bring prose to life with figurative language

Figurative language can add life, color, and depth of meaning to complex or dry concepts. It will express nuance or demonstrate real and tangible qualities that plain language might struggle to convey.  Some common examples are:  

• Simile: Saying something is like something else (e.g., “Computer Malware can spread like a virus.”)
• Metaphor: Saying something is something else (e.g., “Malware is a virus that preys on software.”)
• Analogy: Saying something is like something else to make an explanatory point. (e.g., “Not all malware is business-critical. Some malware is simply annoying and time-consuming, like a common cold is to the human body.”)

Technical writing is full of figurative language. Common phrases like computer bugs, patch releases, front-end caches all come from other references (in this case, illness, clothes mending, and storage) and help clarify meaning.

General Guidelines for figurative language

• Language should be universally understood: Since a lot of our content is translated, we use metaphors that are translatable and country-agnostic. Avoid cultural references, idioms, and colloquialisms that could be meaningless or offensive in other cultures—i.e. “He was a Benedict Arnold.”
• Use figurative language to clarify complex concepts. Extended metaphors can help simplify concepts. Always explain the concept in real terms using plain language, either preceding or following the metaphor. Never rely solely on metaphors for understanding.  (See this primer on containers for an example of a good extended analogy using “bricks and architects.”) 
• Use analogies to help make raw or dull data more interesting and help people visualize it. For example, "That’s enough cable to go to the moon and back 3 times," "That’s enough electricity to power the city of New York for a week." (from chapter 19 of "Everybody Writes" by Ann Handley).
• Compare objects with natural connections or inherent similarities. I.e. Compare two things that grow, like a garden and a customer base: “Consistent customer communications are like watering your garden.”
• Use metaphorical language sparingly: Too many metaphors or “mixed metaphors” can overwhelm readers and obfuscate rather than clarify. Try to limit yourself to one or two usages per article.
• When in doubt, go with simple language. Not everything requires a metaphor. They should only be there if they add life, color, or depth to your piece and should never be used at the expense of clarity. 

Use non-violent language

We aim to use non-violent language because:

• We communicate to connect. Non-violent language helps create and strengthen connections. Violent language separates, categorizes, and destroys.
• Modern strategy models focus on bringing value to customers by understanding their needs and solving their problems compellingly and uniquely. War metaphors are not only cliché and tired, but are poor strategy (as outlined in this piece by Frank V. Cespedes, Stop Using Battle Metaphors in Your Company Strategy). 
• Collaboration, creativity, and diversity are important for most organizations today. Culture is central to that, and a major component of culture is the way we communicate with each other.  Non-violent language helps immensely.

We use non-violent language by replacing metaphors around war with other, more peaceful, constructive ones like art, carpentry, and gardening. For inspiration, check out The Language of Peace: Constructing Non-Violent Metaphors, notes from a workshop by Dr. M.J. Hardman.

Examples

• Before: head-to-head comparison
• After: side-by-side comparison

• Before: Translation support is a powerful weapon in your CMS arsenal.
• After: Translation support is a powerful tool in your CMS toolkit.

Use inclusive language

Be inclusive. Our goal is to help readers feel respected and welcomed. Inclusive language demonstrates empathy for readers. Non-inclusive language shows prejudice, bias, discrimination, or a lack of sensitivity. And as we said under Use non-violent language, “We communicate to connect.” Non-violent language helps create and strengthen connections. Violent language separates, categorizes, and destroys.

Ask and respect. If you’re writing about a person, ask the subject about how they prefer to be identified. The general rule is person-centered language, but it’s not true in all cases. It’s best to ask and inform the reader of the subject’s preferences. See the Talking about people section of the NICE style guide.

Pronouns. If you need to use pronouns throughout an article, balance the use of she/her with he/him. We prefer to use a majority of she/her instances. The singular “they” is also acceptable. 

Remove Bias. We work to remove bias from our language. Inherent biases around gender, race, religion, body types, and other issues are often difficult to see in ourselves. 

• Buffer’s Incomplete Guide to Inclusive Language is a practical overview of some practices and principles. 
• You can test your implicit biases with this Harvard tool.

Address readers directly

Try to use “you” instead of “they” or the archetypal persona (“developers”). 

The direct address makes people feel spoken to. Try to address readers sporadically throughout a blog post. 

• Before: Developers like Technology X because it makes deployment easier for them.  
• After: Technology X will make your deployments easier. 

Don’t criticize 

Stay positive and constructive. If you don’t know your readers’ context or circumstances, you can’t tell them, “you’re doing it wrong.” Likewise, people shouldn’t be blamed for inherited software or systems. Highlight the helpful features of the product you’re promoting to describe a brighter future for your readers.

Focus on the product, not the person. 

• Before: Many developers get overwhelmed by system maintenance. Technology X minimizes maintenance issues, so it’s not so hard for you. 
• After: Complicated system maintenance hinders your development. Technology X minimizes maintenance issues, so you can focus on your work. 

Don’t write negative copy or FUD (fear, uncertainty, and disinformation)

• Before (example from a podcast ad): “If you’re still using TECH X, you’re wasting your time.”
• After (theoretical): “Switching to TECH Y, can double your deployment frequency, leaving you time to do other important things.” [Of course, we need to be able to prove that claim.]

Word Choice and Mechanics

Lean towards simple language. While being colorful, interesting, and accurate, be straightforward. This is not only important for the large number of non-native speakers we assume are consuming what we write. Non-experts in a given field also need to be given a chance to learn from our content.

We want our readers to grasp our intentions and message quickly and confidently. We support this in how we structure our writing—intro/body/recap, don’t bury the lede, etc.—and in our choice of specific words.

Use American spelling 

Select “English (American)” in Google Docs by navigating to file > language. 

Double-check your words’ meanings

Look up definitions (use the Merriam-Webster dictionary or Vocabulary.com). If you think of a word, but it doesn’t sound or look quite right, onelook.com has a great thesaurus with filters for syllables, syntax, and more. 

Opt for Readability

Use tools to check readability including Grammarly, Hemingway Editor, and Simple English.

Avoid regional or colorful language and idioms in favor of clarity. Say what you mean.

• Before: Some managers can’t see the woods for the trees
• After:  Some managers can’t see beyond their daily tasks. 

Use technically accurate language 

Accuracy is extremely important.  This is true for all writing but especially applies to writing about technology. Technical accuracy establishes your credibility with audiences who automatically filter out hyperbole-laden or inaccurate marketing materials. 

We lean on subject-matter experts (SMEs) and capture interviews to ensure we’re as accurate as possible. Even if you quote an expert precisely, have someone check your work to ensure you’ve accurately conveyed their expertise—they may pick up on a slight fault that could undermine your piece. Make sure any code snippets are formatted correctly and run without error. 

Don’t use phrases that cannot be substantiated, like “the best” or competitive comparisons:

• Before: TYPO3’s editing tools are better than other CMSs’. 
• After: TYPO3’s structured content and flexible workflows help editors get their tasks done. 

Use available evidence to back up your claims. 

• Before: TYPO3 has best-in-class security features. 
• After: TYPO3 was ranked first among open source CMSs in addressing vulnerabilities by SecurityRankerTM.  

Explain and decode jargon, abbreviations, and acronyms

Explain technical terms and describe technologies to make sure your audience (with their relevant levels of experience) is on the same page as you. Define technical terms directly in the article and link to other articles with deeper explanations where it makes sense.   Below are a few examples:

• Quick/advanced: CSS styling
• Longer/more helpful: CSS, or “cascading style sheets,” are the code files used to define the look and feel of websites.

• Quick/advanced: Kubernetes container orchestration
• Longer/more helpful: Kubernetes, a container technology for managing large numbers of applications in the cloud...

Age-proof your content

Avoid using words or phrases that need context and go out-of-date. Your piece can become inaccurate or indecipherable to someone reading the piece in the future.

• Avoid: “this year”, “last week”, “recently”, “coming soon.”
• Exception: When you need to place limits on the useful life of a post, for example, “Version 10.2 is new as of June 2021”.

Quote directly

Quote your SME’s directly wherever possible—and have them review the content before publishing. Technical audiences are allergic to technical inaccuracies. Using the wrong term or technical context in a post can turn off developers to your whole offering. Quoting your SME directly saves you from having to know everything (about everything!) and makes it much more likely your content will be accurate.

Guidelines:

• Always introduce the speaker of the quote with their full name, and their role and/or expertise, and/or relevant experience (if important). 
• Use quotation marks. 
• Use present tense verbs: “Emma Bovary explains,” or, “says Emma Bovary.”
• After the first quote, use only the speaker’s last name:  “says Bovary.”
• Punctuate inside the quotation marks.

In our work at OSP, we often interview non-native English speakers. Direct transcriptions of quotes can often be grammatically incorrect. As a writer, you might feel reluctant to change someone’s quoted words. It’s okay to correct the grammar. Use change tracking, and check with the speaker to get their approval and ensure you’ve preserved the intent of the message.

Grammar Choices 

By default, we follow the grammar rules listed on Grammarly. Exceptions and rules we want to highlight are listed below. 

Dashes and hyphens

We follow the spacing and application rules listed on Grammarly.

• The Mighty em-Dash (—): We use the em-dash as super punctuation, to introduce and separate clauses and words.
• Hyphens (-): We use hyphens to connect and join words. 

Spaces around the em-dash? This is not a hard-and-fast rule.

• Generally, no spaces. In body text, we prefer the “old school” use of em-dashes with no spaces between them and the surrounding text.
• However, this can lead to awkwardly long word clumps and formatting problems across different line widths in responsive designs, especially in page headers, taglines, or large-sized text.
• Add spaces around em-dashes to account for visual flow or line breaks in responsive design. And when you think it is the right thing to do.
• Use this power for good.

We <3 Oxford Commas

They are useful, clear, and visually pleasing. Grammarly explains more about the Oxford Comma.

Accessibility

We lean on the Stanford University IT Office of Digital Accessibility resources to make sure we’re using accessible language. Be mindful of readers relying on screen readers or other assistive devices. 

Images

Describe images using alternative text (alt text).

• Be accurate, specific, and concise: use 125 characters or fewer, while providing a meaningful description of the image. 
• You don’t need to take up valuable characters with, “photo of,” or “image of.” Assistive technologies will announce when they are describing an image.

The Stanford University IT Office of Digital Accessibility has some great tips and more information on their Images page. 

• Before: Photo of man in a room full of art supplies and tools.
• After: Dr. Seuss explaining his methods in his art studio.

Hyperlinks 

Always use descriptive text for links. Never use “click here”. The purpose of the link should be obvious from the link text. The Stanford University IT Office of Digital Accessibility explains it well on their Hyperlinks page.

• Before: Click here to find out more about our company.
• After: Find out more on the Meet the Team page.

Use links as call-to-actions. When we want our readers to take action, convert, move to the next stage in the funnel, read the next blog post in a series, we use a link with a clear call-to-action. This tempts the reader by promising something new on the other side of the click. Call-to-actions take the reader to a different piece of content. Use them anywhere where you want the reader to click.

• Get in touch to book a demo!
• Contact us with your project needs today!
• See how much you would save by switching to the Peanut-Matic-5000!
• Start your journey to a more peanut-filled life today.

User links as citations or sources. We use links to other sources for various reasons in online content. When we need to provide access to some information but hope that our readers won’t leave our page, we spell out information in the link. Telling the reader what they’ll find in the link makes clicking it redundant—a “don’t click me” link that keeps the reader on the page. Use citational links to back up a claim or offer background and context. They should not address readers directly. 

• Nine out of ten dental professionals say they prefer peanuts.
• Case studies are the second most popular content asset with B2B content marketers.
• 73% of BSB marketers use case studies in their content marketing.

Writing Workflow

When you need to produce content regularly, you can’t always rely on inspiration to hit when you need it.  At OSP, we trust processes over creativity. 

We have created a transparent, systematic way to prepare, write, and edit content. Our structured approach to writing and editing gives clear guidance to writers, removing the fear factor of the blank page. 

A quick note on tools

Collaborate: We strongly recommend working in an online, medium that auto-saves to the cloud, (for example, Google Docs or Grammarly). This helps us collaborate asynchronously, and recover from technical issues with local computers. We generally write and edit in Google Docs and find it helpful to:

• Use “Editing” mode in Google Docs when drafting a piece.
• Be transparent to learn from each other (authors and editors).
  • Use “Suggesting” when editing someone else’s work
  • Use comments to provide feedback and make suggestions

Reuse: We keep documented templates for common content deliverables (case studies, blog posts, landing pages, etc.) in a Google Docs templates gallery. These give us a head start, be consistent, and teach, onboard, and share how we approach content structure. 

Step 0: Ideas and Inspiration

What are you writing and why? The assignment might come from an editorial plan, client meeting, or strategic framework, and should outline both the subject matter and the purpose of the content (e.g., subject: blog post of CDNs, purpose: highlight expertise in performance). This part of the process usually takes place in conversation with our clients. 

Before writing anything, make sure you understand the following:

• Thesis: What are you trying to say about your topic?
• Target audience: Based on the strategic purpose of the post, who are you trying to reach? (e.g. Developers, business analysts, CMOs, open source contributors, etc.) 
• Goals: What are you trying to achieve from this post?
  • Reader-focused: Inform, inspire, motivate, sign up, etc.
  • Client-focused: Win new business, convince a new partner, motivate a potential new employee to apply, book a demo, etc.
• Format: What type of content are you writing? (e.g., blog post, case study, landing page, infographic, etc.)
• Channels: Where will readers find it? (e.g., Client website, third party site, news outlet, etc.)
• Voice and tone: What’s your client’s voice and tone? Content should reflect the client’s brand voice and be appropriate for the publishing channel. 

Step 1: Interview & Research

We research and conduct interviews to gain a deeper understanding of technical concepts and to develop a sense of the potential narrative. To prepare for an interview, you can read materials related to the subject (e.g., documentation, previous publications by the subject-matter experts, or related blog posts.)This research informs our interview questions.

Interviews with subject-matter experts form the backbone of much of our work. The people we’re interviewing may be experts directly involved in a given product, or they may be product users. Each speaks from experience, providing anecdotal proof and compelling stories. Throughout an interview, the shape of a narrative will usually emerge as we ask our subject-matter experts exploratory questions, for example:

• What problem or task were you faced with?
• How did you think about possible solutions?
• How did you choose or implement a solution?
• What difference has it made for you, your customers, or your peers? 

We use Google Meet to conduct interviews and usually record them. Ask your interviewee if it’s okay to record your discussion through Google Meet, so you can reference it later in the writing process. 

Step 2: Brief

The OSP Content Brief is a basic list of requirements for any given type of asset. Our briefs are critical to our process, and we use them for any writing task from small to large, including articles, case studies, blog posts, landing pages, testimonials, tutorials, and more.

Various strategic elements can inform the brief, such as: 

• Research
• Personas
• Client voice and tone
• Editorial plans 
• Campaigns

The brief sits at the top of the working document. By the time you’ve completed a brief, you will have clearly defined the key objectives of your piece and created a draft outline. 

Why we write briefs

A brief provides us with a clearly thought-out purpose before we start writing copy. It helps us focus our writing, build a strong narrative, make a compelling case for our thesis, and better connect to our audience. 

Process over creativity

A brief helps us get started, keep up the momentum, and share work with clients and colleagues. Once you start writing, you’re filling out details and building on previously defined points, rather than beginning with a blank screen. 

Fail fast

We get a client to review and sign off on a brief so we have a consensus on the thesis and the ideas before we start the draft. If a client or colleague makes suggested edits or structural notes, you can implement them before investing time in copywriting and editing. 

Modularity

You may have a great concept and research, but no time to write. Handoff the brief! Another team member can pick up where you left off. 

Key elements of our brief

Some briefs for specific asset types contain factors that others might not, but most briefs have a standard set of requirements.  It’s hard for us to do a good job and be consistent and efficient without the following information:

• Thesis: Main idea. What the content is about. Direct message.
• Brand Message: Indirect message. What we want the reader to take away about the brand.
• Target Audience: Who is this for?
• Pain Points: Target audience’s challenges
• Business Goals: Awareness, Conversion (define in CTA and/or CTV), Monetization
• CTA/CTV: What is the next step we’d like them to take? 

• Outline:
  • Thesis: [Main Idea]
  • Supporting theme
    • Supporting point
    • Supporting point
  • Supporting theme
    • Supporting point
    • Supporting point
  • Supporting theme
    • Supporting point
    • Supporting point
  • Conclusion / CTA: [Closer]

The Content Brief is a living document at OSP. We continually update and improve the brief, so feedback is encouraged! 

Step 3: Brief Approval

Client review

The client should always review the brief. The brief is, by nature, brief, so this is not a long time commitment for them, and provides a valuable opportunity for course correction.

Internal review

A peer review can help make certain the brief makes sense, and identify missed opportunities or supporting points.

Step 4: Draft

This is when the writing begins. Use the outline from the brief to create your structure and start adding details and evidence around your supporting points. Connect the points, adding headlines and subheads last. 

It’s usually easiest to fill in the body of your piece before drafting the headline and introduction, but follow your intuition as to what works best for you. Make sure to read your draft thoroughly and copy edit before handing it over for review.

Get through your first draft quickly. 

In the first stage of draft creation, don’t worry about language or polish—just get the ideas fully formed onto the page. Once you’re done with round one, you can self-edit and add more stylistic touches before handing it over for internal review. 

Leave a guide for your editors

Mark up any problem areas or queries you may have for the editor. They’ll likely have a fresh viewpoint and can help you overcome challenges like word choices or troublesome sentences.

Step 5: Edit

Editing is an iterative process. At OSP, we approach it as a conversation and learning opportunity between peers. Read more about our editing workflow in our Editing Guide.

Self-review: Review your own work before sending it to others. Download the Grammarly.com extension and run a check on your work. 

Early peer feedback: If you’re stuck on where things should go, need more input or inspiration, submit something for a review when you’re only partially done. Tell the reviewer the state it is in (e.g., “I think this is about half done,” or “I am stuck on this point”), and the reviewer won’t be poking at grammar and polish issues but can give some feedback on bigger issues like structure, concepts, and so on. 

OSP internal review: Once you’re happy with your draft, submit it to an OSP editor for review. They will mark it up and get it ready for client feedback. You can “review the review” and make edits before submitting the piece for client review. 

Client review: Submit the piece to the client for their review and approval. This stage may also include:

• Quote approval: Mark up any direct quotes explicitly and check with the speaker to get their approval. We generally share the full document in Google Docs with the speaker and comment on their quotes to “assign” reviews to individuals. 
• Technical/legal review: During the draft stage, you may need to submit the content for a technical or legal review. Make sure the reviewer knows whether the content has been copyedited or polished already. 

Step 6: Approval

Once we have incorporated client feedback, polished the language, and implemented all necessary assets, the document should be ready for approval. Get approval from the client whose name will be on the post, along with any necessary stakeholders. 

We often provide metadata (meta title and meta description) and draft social media posts (Twitter, LinkedIn, Facebook, etc.) with client deliverables. Sometimes we provide images and screenshots. Most clients take things from there, but our part in the actual publishing varies by client and project.

Tip: Quote approval and technical review are essential before publication, but can happen at any stage in the process that makes sense for the people involved. Since context is everything, the quote source (or the lawyers!) might want to see the otherwise finished article before they approve their quote. 

Step 7: Publish

After approval, you can move your post to the publishing pipeline. This depends on the client’s publishing process. It varies from a simple hand-off to coordinating with one or more contacts and teams who handle publishing. Sometimes, we’re even responsible for posting content onto various platforms for our clients.