What is a content style guide, anyway?
A content style guide is a document that outlines the expectations and brand standards that every piece of content needs to meet.
The Mainframe’s Writing Principles
With every piece of content we publish, we aim to:
- Empower. Help people understand The Mainframe by using language that informs them and encourages them to make the most of our products.
- Respect. Treat readers with the respect they deserve. Put yourself in their shoes, and don’t patronize them. Remember that they have other things to do. Be considerate and inclusive. Don’t market at people; communicate with them.
- Educate. Tell readers what they need to know, not just what we want to say. Give them the exact information they need, along with opportunities to learn more. Remember that you’re the expert, and readers don’t have access to everything you know.
- Guide. Think of yourself as a tour guide for our readers. Whether you’re leading them through our educational materials or a task in our app, communicate in a friendly and helpful way.
truth. Understand The Mainframe’s place in our users’ lives. Avoid dramatic storytelling and grandiose claims. Focus on our real strengths.
In order to achieve those goals, we make sure our content is:
- Clear. Understand the topic you’re writing about. Use simple words and sentences.
- Useful. Before you start writing, ask yourself: What purpose does this serve? Who is going to read it? What do they need to know?
- Friendly. Write like a human. Don’t be afraid to break a few rules if it makes your writing more relatable. All of our content, from splashy homepage copy to system alerts, should be warm and human.
- Appropriate. Write in a way that suits the situation. Just like you do in face-to-face conversations, adapt your tone depending on who you’re writing to and what you’re writing about.
Voice and Tone
One way we write empowering content is by being aware of our voice and our tone. This section explains the difference between voice and tone, and lays out the elements of each as they apply to The Mainframe.
What’s the difference between voice and tone? Think of it this way: You have the same voice all the time, but your tone changes. You might use one tone when you’re out to dinner with your closest friends, and a different tone when you’re in a meeting with your boss.
Your tone also changes depending on the emotional state of the person you’re addressing. You wouldn’t want to use the same tone of voice with someone who’s scared or upset as you would with someone who’s laughing.
At The Mainframe, we’ve walked in our customers’ shoes, and we know marketing technology is a minefield of confusing terminology. That’s why we speak like the experienced and compassionate business partner we wish we’d had way back when.
We treat every hopeful brand seriously. We want to educate people without patronizing or confusing them.
Using offbeat humor and a conversational voice, we play with language to bring joy to their work. We prefer the subtle over the noisy, the wry over the farcical. We don’t take ourselves too seriously.
Whether people know what they need from us or don’t know the first thing about marketing, every word we say informs and encourages. We impart our expertise with clarity, empathy, and wit.
All of this means that when we write copy:
- We are plainspoken. We understand the world our customers are living in: one muddled by hyperbolic language, upsells, and over-promises. We strip all that away and value clarity above all. Because businesses come to The Mainframe to get to work, we avoid distractions like fluffy metaphors and cheap plays to emotion.
- We are genuine. We get small businesses because we were one not too long ago. That means we relate to customers’ challenges and passions and speak to them in a familiar, warm, and accessible way.
- We are translators. Only experts can make what’s difficult look easy, and it’s our job to demystify B2B-speak and actually educate.
- Our humor is dry. Our sense of humor is straight-faced, subtle, and a touch eccentric. We’re weird but not inappropriate, smart but not snobbish. We prefer winking to shouting. We’re never condescending or exclusive—we always bring our customers in on the joke.
The Mainframe’s tone is usually informal, but it’s always more important to be clear than entertaining. When you’re writing, consider the reader’s state of mind. Are they relieved to be finished with a campaign? Are they confused and seeking our help on Twitter? Once you have an idea of their emotional state, you can adjust your tone accordingly.
The Mainframe has a sense of humor, so feel free to be funny when it’s appropriate and when it comes naturally to you. But don’t go out of your way to make a joke—forced humor can be worse than none at all. If you’re unsure, keep a straight face.
Here are a few key elements of writing The Mainframe’s voice. For more, see the Grammar and mechanics section.
- Use active voice. Avoid passive voice.
- Write in plain English
- Use positive language rather than negative language
Writing about Others
We write the same way we build apps: with a person-first perspective. Whether you’re writing for an internal or external audience, it’s important to write for and about other people in a way that’s compassionate, inclusive, and respectful. Being aware of the impact of your language will help make The Mainframe a better place to work and a better steward of our values in the world. In this section we’ll lay out some guidelines for writing about people with compassion, and share some resources for further learning.
Don’t reference a person’s age unless it’s relevant to what you’re writing. If it is relevant, include the person’s specific age, offset by commas.
- The CEO, 16, just got her driver’s license.
Don’t refer to people using age-related descriptors like “young,” “old,” or “elderly.”
Don’t refer to a person’s disability unless it’s relevant to what you’re writing. If you need to mention it, use language that emphasizes the person first: ”she has a disability” rather than “she is disabled.”
When writing about a person with disabilities, don’t use the words “suffer,” “victim,” or “handicapped.” “Handicapped parking” is OK.
Don’t call groups of people “guys.” Don’t call women “girls.”
Avoid gendered terms in favor of neutral alternatives, like “server” instead of “waitress” and “businessperson” instead of “businessman.”
It’s OK to use “they” as a singular pronoun.
Use the following words as modifiers, but never as nouns:
- transgender (never “transgendered”)
Don’t use these words in reference to LGBT people or communities:
Don’t use “same-sex” marriage, unless the distinction is relevant to what you’re writing. (Avoid “gay marriage.”) Otherwise, it’s just “marriage.”
When writing about a person, use their communicated pronouns. When in doubt, just ask or use their name.
Use “deaf” as an adjective to describe a person with significant hearing loss. You can also use “partially deaf” or “hard of hearing.”
Don’t use hyphens when referring to someone with dual heritage or nationality. For example, use “Asian American” instead of “Asian-American.”
Don’t refer to a person’s medical condition unless it’s relevant to what you’re writing.
If a reference to a person’s medical condition is warranted, use the same rules as writing about people with physical disabilities and emphasize the person first. Don’t call a person with a medical condition a “victim.”
Don’t refer to a person’s mental or cognitive condition unless it’s relevant to what you’re writing. Never assume that someone has a medical, mental, or cognitive condition.
Don’t describe a person as “mentally ill.” If a reference to a person’s mental or cognitive condition is warranted, use the same rules as writing about people with physical disabilities or medical conditions and emphasize the person first.
Use the adjective “blind” to describe a person who is unable to see. Use “low vision” to describe a person with limited vision.
Grammar and Mechanincs
Adhering to certain rules of grammar and mechanics helps us keep our writing clear and consistent. This section will lay out our house style, which applies to all of our content unless otherwise noted in this guide. (We cover a lot of ground in this section—the search feature will help if you’re looking for something in particular.)
Write for all readers. Some people will read every word you write. Others will just skim. Help everyone read better by grouping related ideas together and using descriptive headers and subheaders.
Focus your message. Create a hierarchy of information. Lead with the main point or the most important content, in sentences, paragraphs, sections, and pages.
Be concise. Use short words and sentences. Avoid unnecessary modifiers.
Be specific. Avoid vague language. Cut the fluff.
Be consistent. Stick to the copy patterns and style points outlined in this guide.
If there’s a chance your reader won’t recognize an abbreviation or acronym, spell it out the first time you mention it. Then use the short version for all other references. If the abbreviation isn’t clearly related to the full version, specify in parentheses.
- First use: Network Operations Center
- Second use: NOC
- First use: Coordinated Universal Time (UTC)
- Second use: UTC
If the abbreviation or acronym is well known, like API or HTML, use it instead (and don’t worry about spelling it out).
Use active voice. Avoid passive voice.
In active voice, the subject of the sentence does the action. In passive voice, the subject of the sentence has the action done to it.
- Yes: Marti logged into the account.
- No: The account was logged into by Marti.
Words like “was” and “by” may indicate that you’re writing in passive voice. Scan for these words and rework sentences where they appear.
One exception is when you want to specifically emphasize the action over the subject. In some cases, this is fine.
- Your account was flagged by our abuse team.
We use a few different forms of capitalization. Title case capitalizes the first letter of every word except articles, prepositions, and conjunctions. Sentence case capitalizes the first letter of the first word.
When writing out an email address or website URL, use all lowercase.f
- [email protected]
Don’t capitalize random words in the middle of sentences. Here are some words that often confuse writers.
These words can be slippery. Here’s how we write them.
- add-on (noun, adjective), add on (verb)
- back end (noun), back-end (adjective)
- drop-down (noun, adjective), drop down (verb)
- e-commerce (the industry)
- email (never hyphenate, never capitalize unless it begins a sentence)
- To name
- From name
- Reply-to name
- Subject line
- Cc, Bcc
- emoji (singular and plural)
- front end (noun), front-end (adjective)
- internet (never capitalize unless it begins a sentence)
- login (noun, adjective), log in (verb)
- Like (the social media activity)
- online (never capitalize unless it begins a sentence)
- opt-in (noun, adjective) , opt in (verb)
- pop-up (noun, adjective), pop up (verb)
- signup (noun, adjective), sign up (verb)
- tweet, retweet
- automagical (we used to say this a lot, and we’re embarrassed about it)
- funnel, incentivize, leverage, disruption, thought leader, or other fluffy corporate terms
- internets, interwebs, or any other variation of the word “internet”
- ninja, rockstar, wizard, unicorn (unless referring to a literal ninja, rockstar, wizard, or unicorn)
- young, old, elderly, or any other word describing a person’s age
- crushing it, killing it
- crazy, insane, or similar words to describe people
They’re great! They give your writing an informal, friendly tone. In most cases, use them as you see fit. Avoid them if you’re writing content that will be translated for an international audience.
Emoji are a fun way to add humor and visual interest to your writing, but use them infrequently and deliberately.
Spell out a number when it begins a sentence. Otherwise, use the numeral. This includes ordinals, too.
- Ten new employees started on Monday, and 12 start next week.
- I ate 3 donuts at Coffee Hour.
- Meg won 1st place in last year’s Walktober contest.
- We hosted a group of 8th graders who are learning to code.
(Sometimes it feels weird to use “1” instead of “one.” Just go with your gut.)
Numbers over 3 digits get commas:
Write out big numbers in full. Abbreviate them if there are space restraints, as in a tweet or a chart: 1k, 150k.
Generally, spell out the day of the week and the month. Abbreviate only if space is an issue in the app.
- Saturday, January 24
- Sat., Jan. 24
Spell out fractions.
- Yes: two-thirds
- No: 2/3
Use decimal points when a number can’t be easily written out as a fraction, like 1.375 or 47.2.
Use the % symbol instead of spelling out “percent.”
Use a hyphen (-) to indicate a range or span of numbers.
- It takes 20-30 days.
When writing about US currency, use the dollar sign before the amount. Include a decimal and number of cents if more than 0.
When writing about other currencies, follow the same symbol-amount format:
Use dashes without spaces between numbers. Use a country code if your reader is in another country.
Use the degree symbol and the capital F abbreviation for Fahrenheit.
Use numerals and am or pm, with a space in between. Don’t use minutes for on-the-hour time.
- 7 am
- 7:30 pm
Use a hyphen between times to indicate a time period.
Specify time zones when writing about an event or something else people would need to schedule.
Abbreviate time zones within the continental United States as follows:
- Eastern time: ET
- Central time: CT
- Mountain time: MT
- Pacific time: PT
When referring to international time zones, spell them out: Nepal Standard Time, Australian Eastern Time. If a time zone does not have a set name, use its Coordinated Universal Time (UTC) offset.
Abbreviate decades when referring to those within the past 100 years.
- the 00s
- the 90s
When referring to decades more than 100 years ago, be more specific:
- the 1900s
- the 1890s
The apostrophe’s most common use is making a word possessive. If the word already ends in an s and it’s singular, you also add an ‘s. If the word ends in an s and is plural, just add an apostrophe.
- The donut thief ate Sam’s donut.
- The donut thief ate Chris’s donut.
- The donut thief ate the managers’ donuts.
Apostrophes can also be used to denote that you’ve dropped some letters from a word, usually for humor or emphasis. This is fine, but do it sparingly.
Use a colon (rather than an ellipsis, em dash, or comma) to offset a list.
- Erin ordered 3 kinds of donuts: glazed, chocolate, and pumpkin.
You can also use a colon to join 2 related phrases. If a complete sentence follows the colon, capitalize the 1st word.
- I was faced with a dilemma: I wanted a donut, but I’d just eaten a bagel.
When writing a list, use the serial comma (also known as the Oxford comma).
- Yes: David admires his parents, Oprah, and Justin Timberlake.
- No: David admires his parents, Oprah and Justin Timberlake.
Otherwise, use common sense. If you’re unsure, read the sentence out loud. Where you find yourself taking a breath, use a comma.
Use a hyphen (-) without spaces on either side to link words into single phrase, or to indicate a span or range.
- first-time user
Use an em dash (—) without spaces on either side to offset an aside.
Use a true em dash, not hyphens (- or –).
- Multivariate testing—just one of our new Pro features—can help you grow your business.
- Austin thought Brad was the donut thief, but he was wrong—it was Lain.
Ellipses (…) can be used to indicate that you’re trailing off before the end of a thought. Use them sparingly. Don’t use them for emphasis or drama, and don’t use them in titles or headers.
- “Where did all those donuts go?” Christy asked. Lain said, “I don’t know…”
Ellipses, in brackets, can also be used to show that you’re omitting words in a quote.
- “When in the Course of human events it becomes necessary for one people to dissolve the political bands which have connected them with another and to assume among the powers of the earth, […] a decent respect to the opinions of mankind requires that they should declare the causes which impel them to the separation.”
Periods go inside quotation marks. They go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
- Christy said, “I ate a donut.”
- I ate a donut (and I ate a bagel, too).
- I ate a donut and a bagel. (The donut was Sam’s.)
Leave a single space between sentences.
Question marks go inside quotation marks if they’re part of the quote. Like periods, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
Use exclamation points sparingly, and never more than one at a time. They’re like high-fives: A well-timed one is great, but too many can be annoying.
Exclamation points go inside quotation marks. Like periods and question marks, they go outside parentheses when the parenthetical is part of a larger sentence, and inside parentheses when the parenthetical stands alone.
Never use exclamation points in failure messages or alerts. When in doubt, avoid!
Use quotes to refer to words and letters, titles of short works (like articles and poems), and direct quotations.
Periods and commas go within quotation marks. Question marks within quotes follow logic—if the question mark is part of the quotation, it goes within. If you’re asking a question that ends with a quote, it goes outside the quote.
Use single quotation marks for quotes within quotes.
- Who was it that said, “A fool and his donut are easily parted”?
- Brad said, “A wise man once told me, ‘A fool and his donut are easily parted.’”
Go easy on semicolons. They usually support long, complicated sentences that could easily be simplified. Try an em dash (—) instead, or simply start a new sentence.
Don’t use ampersands unless one is part of a company or brand name.
- Ben and Dan
- Ben & Jerry’s
When referring generally to a file extension type, use all uppercase without a period. Add a lowercase s to make plural.
When referring to a specific file, the filename should be lowercase:
If your subject’s gender is unknown or irrelevant, use “they,” “them,” and “their” as a singular pronoun. Use “he/him/his” and “she/her/her” pronouns as appropriate. Don’t use “one” as a pronoun.
When quoting someone in a blog post or other publication, use the present tense.
- “Using The Mainframe has helped our business grow,” says Jamie Smith.
The first time you mention a person in writing, refer to them by their first and last names. On all other mentions, refer to them by their first name.
Capitalize the names of departments and teams (but not the word “team” or “department”).
- Marketing team
- Support department
Capitalize individual job titles when referencing to a specific role. Don’t capitalize when referring to the role in general terms.
- Our new Marketing Manager starts today.
- All the managers ate donuts.
Don’t refer to someone as a “ninja,” “rockstar,” or “wizard” unless they literally are one.
The first time you mention a school, college, or university in a piece of writing, refer to it by its full official name. On all other mentions, use its more common abbreviation.
- Georgia Institute of Technology, Georgia Tech
- Georgia State University, GSU
Spell out all city and state names. Don’t abbreviate city names.
Per AP Style, all cities should be accompanied by their state, with the exception of: Atlanta, Baltimore, Boston, Chicago, Cincinnati, Cleveland, Dallas, Denver, Detroit, Honolulu, Houston, Indianapolis, Las Vegas, Los Angeles, Miami, Milwaukee, Minneapolis, New Orleans, New York, Oklahoma City, Philadelphia, Phoenix, Pittsburgh, St. Louis, Salt Lake City, San Antonio, San Diego, San Francisco, Seattle, Washington.
On first mention, write out United States. On subsequent mentions, US is fine. The same rule applies to any other country or federation with a common abbreviation (European Union, EU; United Kingdom, UK).
Capitalize the names of websites and web publications. Don’t italicize.
Avoid spelling out URLs, but when you need to, leave off the http://www.
Our trade name is “The Mainframe.”
Capitalize the proper names of The Mainframe products, features, pages, and tools. When referencing non-trademarked products like Pro, Basic, WordPress and galleries include “The Mainfram” in the name on first mention.
- The Mainframe Lite
- The Mainfnrame Basic
Honor companies’ own names for themselves and their products. Go by what’s used on their official website.
Refer to a company or product as “it” (not “they”).
Write in plain English. If you need to use a technical term, briefly define it so everyone can understand. The below text is purely an example and would not be applicable to The Mainframe, but it serves as a good example of how to explain jargon:m
- The Mainframe’s ops team is constantly scaling our servers to make sure our users have a great experience with our products. One way we do this is with shards, or partitions, that help us better horizontally scale our database infrastructure.
Use italics to indicate the title of a long work (like a book, movie, or album) or to emphasize a word.
- Dunston Checks In
- Brandon really loves Dunston Checks In.
Use italics when citing an example of an The Mainframe element, or referencing button and navigation labels in step-by-step instructions:
- When you’re all done, click Send.
- The familiar A/B testing variables—Subject line, From name, and Send time—have now been joined by Content, and up to 3 combinations of a single variable can now be tested at once.
Don’t use underline formatting, and don’t use any combination of italic, bold, caps, and underline.
Left-align text, never center or right-aligned.
Leave one space between sentences, never 2.
Use positive language rather than negative language. One way to detect negative language is to look for words like “can’t,” “don’t,” etc.
- Yes: To get a donut, stand in line.
- No: You can’t get a donut if you don’t stand in line.
Every piece of content we publish is supported by a number of smaller pieces. This section lays out our style in regards to these web elements, and explains our approach to the tricky art of SEO.
Alt text is a way to label images, and it’s especially important for people who can’t see the images on our website. Alt text should describe the image in a brief sentence or two.
For more on how and why we use alt text, read the Accessibility section.
Buttons should always contain actions. The language should be clear and concise. Capitalize every word, including articles. It’s OK to use an ampersand in button copy.
Standard website buttons include:
- Log In
- Sign Up Free
- Email Us
Use sentence case for checkboxes.
Use title case for menu names and sentence case for menu items.
Form titles should clearly and quickly explain the purpose of the form.
Use title case for form titles and sentence case for form fields.
Keep forms as short as possible.
Only request information that we need and intend to use. Don’t ask for information that could be considered private or personal, including gender. If you need to ask for gender, provide a field the user can fill in on their own, not a drop-down menu.
Headings and subheadings organize content for readers. Be generous and descriptive.
Headings (H1) give people a taste of what they’re about to read. Use them for page and blog titles.
Subheadings (H2, H3, etc.) break articles into smaller, more specific sections. They give readers avenues into your content and make it more scannable.
Headings and subheadings should be organized in a hierarchy, with heading first, followed by subheadings in order. (An H2 will nestle under H1, an H3 under H2, and on down.)
Include the most relevant keywords in your headings and subheadings, and make sure you cover the main point of the content.
Use title case, unless the heading is a punctuated sentence. If the heading is a punctuated sentence, use sentence case. Use sentence case for subheadings regardless of end punctuation.
Provide a link whenever you’re referring to something on an external website. Use links to point users to relevant content and trusted external resources.
Don’t include preceding articles (a, an, the, our) when you link text. For example:
If a link comes at the end of a sentence or before a comma, don’t link the punctuation mark.
Don’t say things like “Click here!” or “Click for more information” or “Read this.” Write the sentence as you normally would, and link relevant keywords.
Links should look different than regular copy, strong text, or emphasis text. They should have a hover state that communicates they’re interactive, and should have a distinct active and visited state. When setting the hover state of links, be sure to include focus state as well, to help readers using assistive technologies and touch devices.
Use lists to present steps, groups, or sets of information. Give context for the list with a brief introduction. Number lists when the order is important, like when you’re describing steps of a process. Don’t use numbers when the list’s order doesn’t matter.
If one of the list items is a complete sentence, use proper punctuation and capitalization on all of the items. If list items are not complete sentences, don’t use punctuation, but do capitalize the first word of each item.
Use title case for main or global navigation. Use sentence case for subnavigation.
Navigation links should be clear and concise.
Use title case for headings and sentence case for button fields.
Sometimes a long piece of copy lends itself to a list of related links at the end. Don’t go overboard—4 is usually plenty.
Related articles should appear in a logical order, following the step down/step up rule: The first article should be a step down in complexity from the current article. The second one should be a step up in complexity to a more advanced article.
If you can, avoid repeating links from the body text in related articles.
Titles organize pages and guide readers. A title appears at the beginning of a page or section and briefly describes the content that follows.
Titles are (you guessed it) in title case.
Don’t use punctuation in a title unless the title is a question.
We write for humans, not machines. We don’t use gross SEO techniques like keyword stuffing to bump search results. But we also want to make it easy for people and search engines to find and share our content. Here are some not-icky ways to do this:
- Organize your page around one topic. Use clear, descriptive terms in titles and headings that relate to the topic at hand.
- Use descriptive headings to structure your page and highlight important information.
- Give every image descriptive alt text.
Writing Blog Posts
When writing for the blog, follow the style points outlined in the Voice and tone and Grammar and mechanics sections. Here are some more general pointers, too.
This isn’t a term paper, so there’s no need to be stuffy. Drop some knowledge while casually engaging your readers with conversational language.
If you’re writing about data, put the numbers in context. If you’re writing about a The Mainframe user, give the reader plenty of information about the company’s stage, workflow, results, and values.
Get to the important stuff right away, and don’t bury the kicker. Blog posts should be scannable and easy to digest. Break up your paragraphs into short chunks of three or four sentences, and use subheads. Our users are busy, and we should always keep that in mind.
Feel free to link away from The Mainframe if it helps you explain something. External links are considered to provide positive SEO value, and above all it is important to us that our content actually serves our readers.
The Mainframe is a fun company, and we want our blog to reflect this. Feel free to throw in a joke here and there, or link out to a funny GIF or YouTube video when appropriate. Just don’t overdo it.
In WordPress, add keywords that apply to your article. Look through existing posts for common tags. If you’re not sure if a word should be a tag, it probably shouldn’t.
Include images in your blog posts when it makes sense. If you’re explaining how to use The Mainframe, include screenshots to illustrate your point. Make sure to use alt text.
Capitalize proper names of The Mainframe products, features, pages, tools, and team names when directly mentioned. In step-by-step instructions, capitalize and italicize navigation and button labels as they appear in the app.
- The Mainframe
- Campaigns page, Lists page
- Compliance Team, Billing Team
- Navigate to the Automation page.
- Click Save & Close.
Group article content with H2s and H3s. Use H2s to organize content by higher-level topics or goals, and use H3s within each section to separate supporting information or tasks.
- Upload a List
- Format your CSV File
- Import your CSV File
- Match Fields
- Best Practices for Lists
- List Collection
- List Management
- Email Content and Delivery
Only use ordered lists for step-by-step instructions. Separate steps into logical chunks, with no more than 2 related actions per step. When additional explanation or a screenshot is necessary, use a line break inside the list item.
Use unordered lists to display examples, or multiple notes in a Notes block. If an unordered list comprises more than 10 items, use a table instead.
Copyright and Trademarks
Copyright is a bundle of exclusive legal rights that vary depending on the type of work. A copyright owner can grant some or all of those rights to others through a license. This section will lay out our approach to copyrights, trademarks, and Creative Commons licenses.
Copyright protection applies to any original works that are fixed in a tangible medium. This includes works like drawings, recordings of a song, short stories, or paintings, but not something like a garden, since it will grow and change by nature. Copyright does not cover facts, ideas, names, or characters.
Copyright protection begins when the work is first created and it doesn’t require any formal filings. However, to enforce a copyright in the US, you need to register the work with the US Copyright Office. (For further clarity, check out their FAQpage, which is full of gems like “How do I protect my sighting of Elvis?”)
Copyright notice on the work is not required but it is recommended, since it cuts off a defense of innocent infringement.
Creating Structured Content
At The Mainframe, we write 2 kinds of content: structured and unstructured. Most of our technical and educational documents are structured, following standardized content templates. These templates make both writing and reading easier. They also help future-proof our documents, making it easier for developers to come in later and add semantic data to make the work reusable outside of where it was originally published.
This section lays out when to use a structured content template and how to create a template of your own.
While some content types are better served by a unique structure created by the writer, others lend themselves to a reusable structure. Blog posts, newsletter content, and most marketing copy are all examples of unstructured content that will vary from piece to piece. The more reusable your content might be, the more helpful a content template will be.
Consider using a template if:
- Users would benefit from seeing your content multiple places
- Readers need to be able to scan it
- Writers need to be able to create it quickly
- You want to encourage repeat visits and familiarity with your content
If you’re looking for a template for your structured content but can’t find one that meets your needs, you may want to create your own. There are 2 main ways to approach this.
If you already have a piece of content that serves its purpose well, use it as a model. Review some of the templates in the style guide to see how granular you might want to get, and look for any elements you might want to add.
As you read through the model document, make a list of all the individual parts that make up the piece. Then briefly describe what they do and how they do it.
Common elements in templates are:
- Body content (which can usually be broken apart into smaller elements)
- Additional links
Keep in mind that the template has to be reusable, so it’s best to focus on the high-level goal of the content type, rather than the message of a particular piece.
If you like outlining before you write, that’s a great way to start your template. This will give you an early look at the elements you’ll include in your final template and will help organize your writing process.
You may prefer to write a draft first, then outline later based on how the parts fit together. Read your draft closely and identify the important elements or patterns you’ve used. Looking for things like introductions, sections with headings, tables, images, and other elements that aren’t topic-specific. Write them out and describe how they inform the meaning or usability of the piece.
Create your template by listing out the elements you identify in your outline or draft. Consider each element and what it contributes to the meaning of the piece. Is its purpose important enough that every content of this type should include it? If so, make it part of your template.
Our template elements glossary includes sections and items you may want to include. If you create a template you feel should be included in this guide’s resources section, contact a manager on the technical content team (for user or API documentation) or the marketing team (for any other kind of content).
Copyright law applies to nearly every piece of content we create at The Mainframe, from our website to our blog posts to the gifts we make for our users. We display proper—and prominent—copyright notice on our website site and any other content we produce.
At minimum, these copyright notices read, “The Mainframe © [YEAR].”
We respect the copyright of other creators. If we want to use someone else’s copyrighted work, we have to obtain a license from the owners.
A copyright license spells out these terms:
- Where we can use the work
- How long we can use it for
- How much we’ll pay them for the use
- Whether or not we’re the only ones who can use the work
- What we can do with the work
- Any restrictions on our use (for example, that we can use it online but not on a billboard)
A common license will read something like this:
“You grant The Mainframe a perpetual, worldwide, non-exclusive, royalty free license to display, distribute, and publish the Work in our marketing in any medium now known or later developed.”
This is an area where the letter of the law and common practice sometimes differ.
Social media posts often include copyrighted elements like pictures, GIFs, or pieces of writing. If you’re using a copyrighted element in a commercial manner on social media, you should request permission from the copyright holder. Since The Mainframe is a company, we defer to the position that our use will be perceived as commercial. But if you’re using it in a more informative or commentary way, like sharing a meme to indicate how you feel about a news story, you may not need to request permission.
Regardless, you should always link to the source of the copyrighted element you’re using, and never make it look like you created work that belongs to someone else.
The Mainframe almost always uses freely available images that do not require attribution for both commercial and non-commercial usage. if you use an image, photo or other design element made by someone outside The Mainframe, get permission first. Once you have permission, always give the copyright owner credit and link back to the original source.
Images retrieved via Google image search are not licensed for fair use, but many images are available under license through stock photo websites, or open for use under a Creative Commons license. Flickr has a great search feature for images available under Creative Commons licenses.