The Cholangiocarcinoma Foundation (CCF) does not expect its staff or volunteers to know all the rules of its style guide. That is why we are being proactive by providing one for reference with instructions on when to consult it.

CCF encourages its staff and volunteers to become familiar with the biggest differences among styles, and to check the guide when you have questions. CCF has chosen to write in Chicago style with use of the Oxford hard comma except with communication that is earmarked for the media and press. Below is other writing styles CFF has adopted:

• Headline capitalization: AP style uses sentence case, while Chicago uses title case. Depending on our deliverable, CCF uses both.
• Citation: MLA, APA and Chicago each offer templates for citing sources within a paper or a reference list. Citation will be used by any CCF academic works.
• Punctuation: Notably, guides differ in their recommendations for the Oxford comma, the percent symbol, hyphens and dashes.
• Numbers: Whether to spell a number or use a figure varies among style guides and even within each, depending on how you use the number. Also look up how to handle dates, ages and time.
• Compound words: Recommendations for compounds change quickly, especially as words become common. Check a current guide for whether to write health care, healthcare, or health-care, for example.
• Abbreviations and acronyms: Should you use a state abbreviation (like Fla.) or a postal code (like FL)… or always spell it out? In acronyms like U.S., do you need the periods? AP says yes, Chicago says you can go either way. CCF will use both depending on the deliverables.
• Formatting: Chicago and APA italicize book titles, while AP uses quotation marks around them. Guides also include preferences for formatting bulleted lists, block quotes, sentence spacing and more. (Double spacing is no longer needed.)
• Words about technology: Common usage changes quickly, and your content can look outdated if it doesn’t keep up — for example, a hyphen in “e-mail” or capitalizing “Internet.” Check your current style guide for recommendations, but also address these in house style if conventional guidance doesn’t make sense for your audience.
• Brand names: Will you use camel case for eBay and iPhone? All-caps for IKEA? A hyphen in Wal-Mart or Walmart? CCF style addresses its brand names depending on its audience.
• Identifying groups of people: The boundaries for respectful and inclusive language are ever-shifting so terms you’re accustomed to could be outdated. AP style, complementary media guides and APA style include up-to-date guidance based on common usage and recommendations from advocacy groups. CCF refers to those within its industry and doesn’t include preferences.

With every piece of content CCF publishes, our goal is to:

• Empower. Help people understand the Foundation’s mission and core values by using language that informs them and encourages them to engage.
• 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.
• Speak truth. Understand CCF’s place in users’ lives. Avoid dramatic storytelling and grandiose claims. Focus on our real strengths.

To achieve those goals, we make sure our content is:

• Clear. Understand the topic we are writing about. Use simple words and sentences.
• Useful. Before we start writing, we ask ourselves: What purpose does this serve? Who is going to read it? What do they need to know?
• Friendly. Write like a human. We aren’t afraid to break a few rules if it makes our writing more relatable.
• Appropriate. Write in a way that suits the situation. We adapt our tone depending on who we’re writing to and what we’re writing about.

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.

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.

Our tone changes depending on the emotional state we’re addressing. Our voice doesn’t change much from day to day, but our tone may change all the time.

Voice

At CCF, we speak like an experienced and compassionate partner of those affected by cholangiocarcinoma. We want to educate people without patronizing or confusing them.

Whether people know what they need from the Foundation or don’t know the first thing about cholangiocarcinoma, every word we say informs and encourages. We impart our expertise with clarity, empathy, and knowledge.

All of this means that when we write copy:

• We are plainspoken. We understand the world cancer patients and their caregivers are living in with medical terminology, drug names and treatment options following diagnosis. We offer a way to make sense of it to give clarity and understanding.
• We are genuine. We care! Majority of the CCF staff have been directly impacted by cholangiocarcinoma. That means we relate to challenges and we address them in a positive, accessible way.
• We are translators. Only experts can make what’s difficult look easy, and it’s our job to demystify cholangiocarcinoma and actually educate.

Tone

CCF’s tone is usually formal because it is always important to be clear. 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? Once you have an idea of their emotional state, you can adjust your tone accordingly.

CCF does write informally when it’s appropriate, such as with certain campaigns and forward-facing public social media posts.

Style Tips

Here are a few key elements of writing CCF’s voice.

• Active voice Use active voice. Avoid passive voice.
• Avoid slang and jargon Write in plain English.
• Write positively Use positive language rather than negative language.

The Cholangiocarcinoma Foundation is straightforward with what its premise is all about – cholangiocarcinoma.

Upon first reference, its name is always spelled out. In adherence to AP style, upon second reference the name is referred to Foundation with a capital F or abbreviated to CCF.

We never break up our name to create new names whether for a service or program.

We write with a patient-first perspective. Whether we’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 our language helps make the Foundation a trusted place to facilitate collaboration and be a clearinghouse of resources for patients, caregivers, scientists, researchers, and others. In this section we’ll lay out some guidelines for writing about people with compassion.

As part of an audience

• Don’t capitalize “audience” unless it’s grammatically necessary.
• Don’t refer to an audience as “it.” Audiences are made up of real people, so always use “they.”
• This goes for contacts, too. Contacts are real people, never pieces of data.
• There’s a feature in our app called “lookalike audiences,” which is a way for our customers to market to people who are similar to their existing contacts. Always use the “lookalike” qualifier when referring to this feature to avoid confusion.

Age

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

Disability

Avoid disability-related idioms like “lame” or “falling on deaf ears.” Don’t refer to a person’s disability unless it’s relevant to what you’re writing. If you need to mention it, ask whether your subject prefers person-first language (“they have a disability”) or identity-first language (“they are disabled”).

When writing about a person with disabilities, don’t use the words “suffer,” “victim,” or “handicapped.” “Handicapped parking” is OK.

Gender and sexuality

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:

• lesbian
• gay
• bisexual
• transgender (never “transgendered”)
• trans
• queer
• LGBT

Don’t use these words in reference to LGBT people or communities:

• homosexual
• lifestyle
• preference

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.

Hearing

Use “deaf” as an adjective to describe a person with significant hearing loss. You can also use “partially deaf” or “hard of hearing.”

Heritage and nationality

Don’t use hyphens when referring to someone with dual heritage or nationality. For example, use “Asian American” instead of “Asian-American.”

Medical conditions

Don’t refer to a person’s medical condition unless it’s relevant to what we’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.”

Mental and cognitive conditions

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.

Race

When we write about a culture or ethnicity, we capitalize the name. For example, we capitalize Black as it refers to Americans in the African diaspora while we keep white lowercase since white refers to the color of a person’s skin and not a group of people.

Vision

Use the adjective “blind” to describe a person who is unable to see. Use “low vision” to describe a person with limited vision.

Every piece of content we publish is supported by a number of smaller pieces. This section lays out our style with regards to these web elements and explains our approach to the tricky art of SEO.

Guidelines

Alt text

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.

Buttons

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
• Subscribe
• Email Us

Checkboxes

Use sentence case for checkboxes.

Drop-down menus

Use title case for menu names and sentence case for menu items.

Forms

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

Headings and subheadings organize content for readers. They should include the most relevant keywords and cover/highlight the main point(s) of the page.

Headings and subheadings are written in sentence case. Avoid using end punctuation except for question marks or when a heading is two or more sentences.

Organize headings and subheadings hierarchically, with headings first, followed by subheadings in order. (An h3 will nestle under H1, an h4 under h3, and on down.)

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

Links

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.

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.

Lists

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.

Navigation

Use title case for main or global navigation. Use sentence case for subnavigation.

Navigation links should be clear and concise.

Radio Buttons

Use title case for headings and sentence case for button fields.

Related articles

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

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 also tell search engines what a page is about, and show up in search results.

Titles are written (you guessed it) in title case. Don’t use end punctuation in a title unless the title is a question.

SEO

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.

At CCF, we strive to explain technical content in layman’s terms. This section will lay out the guiding principles of technical content, discuss the main types of technical content, and outline the process of writing and editing technical articles.

Basics

Someone reading technical content is usually looking to answer a specific question. That question might be broad or narrowly focused, but either way our goal is to provide answers without distraction.

For each project, consider your audience’s background, goal, and current mood. Ask these questions:

• Is the reader a prospective user, a new user, or an experienced user?
• What is the goal of the user? To complete a task? To research a topic?
• Is the user in the middle of a task? Are they in a hurry? Could they be frustrated?

We don’t want to overload our audience with unnecessary information, choices, or complex ideas or phrases when we don’t have to. This is particularly critical when a user may be new and/or frustrated.

When relevant, provide a brief outline of an article’s focus in an introductory paragraph or section, and stick to the topic at hand. Keep sentences, paragraphs, and procedural steps focused and concise.

Types of technical content

Technical content articles vary in target audience, goal, and tone.

Guidelines

Writing technical content

When writing technical content, we follow style points outlined below.

Stay relevant to the title

When a user clicks the title of an article, they expect to find the answer they want. Don’t stray too far from the title or topic at hand. Use links to make related content available. If you find you’re getting too far from the intended topic, then you may need to create a separate but related article.

Keep headlines and paragraphs short and scannable

Focused users often scan an article for the part that will answer their particular question. Be sure headlines are short, descriptive, and parallel, to facilitate scanning.

Use second person and describe actions to a user

Technical content talks to users when support agents can’t.

Strive for simplicity and clarity

Be as clear as possible. Use simple words and phrases, avoid gerunds and hard-to-translate idioms or words, focus on the specific task, limit the number of sentences per paragraph. If you must include edge cases or tangentially related information, set it aside in a Before You Start list or Notes field.

Provide context through embedded screenshots, videos, and GIFs

Screenshots, videos, and GIFs may not be necessary for every article or process, but can be helpful to orient new users. Crop screenshots tightly around the action to focus attention.

Formatting technical content

Technical content uses organization, capitalization, and other formatting to help convey meaning. Although articles are organized differently, some formatting tips are consistent throughout all technical content.

Capitalization

Capitalize proper names of CCF products, features, pages, tools, and teams when directly mentioned. In step-by-step instructions, capitalize and bold navigation and button labels as they appear in the app.

• Cholangiocarcinoma
• Compliance Team, Billing Team
• Navigate to the Reports page.
• Click Create.

Headings

Organize article content with H2s and H3s. Use H2s for higher-level topics or goals, and use H3s within each section for supporting information or tasks.

Article title: About Landing Pages

• H2: How landing pages work
• H2: How to use landing pages
• H2: Resources
• H3: Get inspired and learn best practices
• H3: Create a landing page
• H3: Learn about reports

Ordered Lists

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.

Unordered Lists

Use unordered lists to display examples or multiple notes. If an unordered list comprises more than 10 items, use a table instead.

CCF publishes may write legal content to protect ourselves and our users around the world. Most of our legal content is written by the Legal consultants with help from the Communications team. This section gives a general overview of the types of legal content we publish and how those documents are written.

Basics

The way we write, review, and publish legal content is different than how we do many other kinds of writing at CCF. The most important difference is that all legal content either starts with or passes through Legal consultation.

But that doesn’t mean legal content has to be difficult to read. We try to present our legal information in the most pleasant way possible. Our goals for CCF’s legal content are:

• Accuracy. Our first and foremost concern is that we present the correct information in a truthful way.
• Clarity. We try to avoid legal jargon and overly formal wording. Our users need to understand the agreement they’re making with us.
• Succinctness. We want our users to read and understand our legal documents, while also respecting their time.

Types of legal content

We publish several types of legal documents, each with their own writing processes and goals.

Public legal documents

We keep these in one place on our legal page:

• Terms of use
• Acceptable use policy
• Privacy policy
• API use policy
• Copyright policy

These policies apply to all of CCF’s users. The Legal and Communication teams work together to make them as transparent and easy to read as possible. When someone signs up to use CCF resources, they must agree to all of those terms.

When new legal documents are published or edited, we notify all our users of the updates and provide a window for them to object before the new terms go into effect.

Public communications

Occasionally we may have to publish communications about security, privacy, and other corporate issues. This could come in the form of an email, a blog post, a public statement, or a press release.

The Communications team works with Legal consultation to write and publish these documents, and the executive team reviews them.

Guidelines

When writing legal content, we use some general considerations, too.

Start with the facts

We have some standard language that we use for common issues or requests, but since legal content is so fact-specific, we start there before getting into structure and format. That’s why you won’t see many templates for our legal content.

Use plain language

Legal content is serious business, so the tone is slightly more formal than most of our content. That said, we want all of our users to be able to understand our legal content. So whenever possible, we use plain language rather than legal jargon.

Instead of: “If an individual purports, and has the legal authority, to sign these Terms of Use electronically on behalf of an employer or client then that individual represents and warrants that they have full authority to bind the entity herein to the terms of this hereof agreement”

We say: “If you sign up on behalf of a company or other entity, you represent and warrant that you have the authority to accept these Terms on their behalf.”

There are some legal terms we have to include because either there’s not a sufficient plain language alternative, or case law or statute dictates that term has to be used for the contract to hold up in court. For example, sometimes we need to say “represent and warrant” instead of “confirm” or “agree.” If we use those terms, we can provide an example or quick definition to help people understand what they’re reading. We can’t avoid all legal terminology, but we can pare it down to what’s necessary.

Some companies have complicated terms and write plain-language summaries so people can understand the agreement. We don’t summarize our legal content, but instead try to write the terms themselves in plain language. We use a sidebar to provide examples or links to further reading for people who want more context.

Definitions

Using plain language for the terms you define up front can make legal documents easier to read. You’ve probably read contracts that say something like “The Corporation” or “The User” throughout, instead of “we” (meaning the company) and “you” (meaning the user who is agreeing to the terms). There’s a quick fix for that. At the beginning of the document, say something like:

• TeamCFF is owned and operated by the Cholangiocarcinoma Foundation, a 501c3, nonprofit charity. (“CCF,” “Foundation” “we,” or “us”). As a user of the Service or a representative of an entity that’s a user of the Service, you’re a “Member” according to this agreement (or “you”).

After that, you’re free to use “we,” “us,” “you,” and “your” throughout the rest of the agreement. That simple change makes the document much friendlier to read.

Contractions

We use contractions in many of our legal documents, which makes them sound more human and flow better with the rest of our content. Contracting words doesn’t affect the validity of an agreement.

Never offer legal advice

While we want to inform our users about legal issues related to their use of Mailchimp, we can’t offer them legal advice. Sometimes it’s a fine line. The legal department will check for this in their content review.

We send a lot of email but we only send them when we have something to say.

Basics

Our email newsletters help empower and inform CCF audiences. Here are the most common types of content we send by email:

• Program, campaign, collaboration, treatment announcements
• Regular monthly newsletters
• Automated series (Newly Diagnosed/Newly Connected)
• Event invitations and information about online resources
• System alerts about any changes to functionality or operations
• Volunteer newsletters

Guidelines

Email newsletters generally follow the style points that include consistency with CCF brand. (Click here for CCF Brand Style Guide)

Consider all elements

Every email newsletter is made up of the following elements. Make sure they’re all in place before clicking send:

From name

This is CCF’s name, program name or name of staff. It identifies the sender in the recipient’s inbox.

Subject line

Keep your subject line descriptive. There’s no perfect length, but some email clients display only the first words. Tell—don’t sell—what’s inside. Subject lines should be in sentence case. (Note that this is different from a headline, which you may want to include in the campaign itself.)

Preheader text

The top line of your campaign appears beside each subject line in the inbox. Provide the info readers need when they’re deciding if they should open.

Body copy

Keep your content concise. Write with a clear purpose and connect each paragraph to your main idea. Add images when they’re helpful.

Call to action

Make the next step clear. Whether you’re asking people to submit something, read something, share something, or respond to something, offer a clear direction to close your message so readers know what to do next.

Footer

All campaigns follow CAN-SPAM rules. Include an unsubscribe link, mailing address, and permission reminder in the footer of each newsletter.

Consider your perspective

When sending an email newsletter from CCF, use the 3rd person “we.” When sending a newsletter as an individual, use the 1st person.

Use a hierarchy

Most readers will be scanning your emails or viewing them on a small screen. Put the most important information first.

Include a call to action

Make the reader’s next step obvious and close each campaign with a call to action. Link to a blog post, event registration, purchase page, or signup page. You can add a button or include a text link in the closing paragraph.

Avoid unnecessary links

More than 50% of emails are read on a mobile device. Limit links to the most important resources to focus your call to action and prevent errant taps on smaller screens.

Use alt text

Some email clients disable images by default. Include an alt tag to describe the information in the image for people who aren’t able to see it.

Segment your audience

It’s exciting to send to millions of users at once, but it’s doubtful that every subscriber is interested in every topic. Segment your list to find a particular audience that’s likely to react.

Once you’ve selected an audience, adjust the language to fit their needs. For example, users who developed custom integrations are more likely to understand and appreciate direct, technical terms.

Test your campaigns

Use the preview mode to begin and run an Inbox Inspection to see your newsletter in different email clients. Read your campaign out loud to yourself, then send a test to a coworker for a second look.

We use social media to build relationships with the public and targeted key audiences. We’re careful and deliberate in what we post to our social channels. This section lays out how we strike that delicate balance.

Basics

CCF has a presence on most major social media platforms. Here are our most active accounts and what we usually post on each:

• Twitter: Events, media mentions, evergreen content, collaborations, campaigns, articles and more.
• Facebook: Events, media mentions, evergreen content, collaborations, campaigns, articles, webinars and more.
• LinkedIn: Events, media mentions, evergreen content, collaborations, campaigns, articles, hiring, advances and more.
• Instagram: Events, media mentions, evergreen content, collaborations, campaigns, articles and more.

These channels are all managed by the Communication team. We also have an account on YouTube.

Guidelines

Our writing for social media follows the style points outlined.

Write short, but smart

Some social media platforms have a character limit; others don’t. But for the most partwe keep our social media copy short.

• Twitter: 280 characters.
• Facebook: No limit, but aim for 1-2 short sentences.
• Instagram: No limit, but try to keep it to 1 sentence or a short phrase. Feel free to throw in an emoji.

To write short, simplify your ideas or reduce the amount of information you’re sharing—but not by altering the spelling or punctuation of the words themselves. It’s fine to use the shorter version of some words, like “info” for “information.” But do not use numbers and letters in place of words, like “4” instead of “for” or “u” instead of “you.”

Engagement

We strive to use correct grammar and punctuation—and avoid excessive exclamation points.

When appropriate, we tag the subject of our post on Twitter or Facebook. But avoid directly tweeting at or otherwise publicly tagging a post subject with messages like, “Hey, we wrote about you!” We rarely ask for retweets, likes, or favorites.

Hashtags

We employ hashtags deliberately. We may use them to promote an event or connect with users at a conference. Do not use current event or trending hashtags to promote the Foundation.

Trending topics

Do not use social media to comment on trending topics or current events that are unrelated to the Foundation.

We strive to be aware of what’s going on in the news when publishing social content for CCF. During major breaking news events, we turn off all promoted and scheduled social posts.

We’re always working to make our content more accessible and usable to the widest possible audience. Writing for accessibility goes way beyond making everything on the page available as text. It also affects the way you organize content and guide readers through a page. Depending on the audience and country, there may be laws governing the level of accessibility required. At minimum, an accessible version should be available. Accessibility includes users of all mental and physical capacities, whether situational (broken glasses!) or more permanent.

Basics

We write for a diverse audience of readers who all interact with our content in different ways. We aim to make our content accessible to anyone using a screen reader, keyboard navigation, or Braille interface, and to users of all cognitive capabilities.

We consider the following:

• Would this language make sense to someone who doesn’t work here?
• Could someone quickly scan this document and understand the material?
• If someone can’t see the colors, images or video, is the message still clear?
• Is the markup clean and structured?
• Mobile devices with accessibility features are increasingly becoming core communication tools, does this work well on them?

Many of the best practices for writing for accessibility echo those for writing technical content, with the added complexity of markup, syntax, and structure.

Guidelines

Avoid directional language

Avoid directional instructions and any language that requires the reader to see the layout or design of the page. This is helpful for many reasons, including layout changes on mobile.

• Yes: “Select from these options,” (with the steps listed after the title)
• No: “Select from the options in the right sidebar.”

Use headers

Headers should always be nested and consecutive. Never skip a header level for styling reasons. To help group sections, be sure the page title is H1, top-level sections are H2s, and subsequent inside those are h4 and beyond. Avoid excessive nesting.

Employ a hierarchy

Put the most important information first. Place similar topics in the same paragraph, and clearly separate different topics with headings.

Starting with a simple outline that includes key messages can help you create a hierarchy and organize your ideas in a logical way. This improves scannability and encourages better understanding.

Make true lists instead of using a paragraph or line breaks.

Label forms

Label inputs with clear names, and use appropriate tags. Think carefully about what fields are necessary, and especially which ones you mark as required. Label required fields clearly. The shorter the form, the better.

Use descriptive links

Links should provide information on the associated action or destination. Try to avoid “click here” or “learn more.”

Use plain language

Write short sentences and use familiar words. Avoid jargon and slang. If you need to use an abbreviation or acronym that people may not understand, explain what it means on first reference.

Use alt text

The alt tag is the most basic form of image description, and it should be included on all images. The language will depend on the purpose of the image:

• If it’s a creative photo or supports a story, describe the image in detail in a brief caption.
• If the image is serving a specific function, describe what’s inside the image in detail. People who don’t see the image should come away with the same information as if they had.
• If you’re sharing a chart or graph, include the data in the alt text so people have all the important information.

Each browser handles alt tags differently. Supplement images with standard captions when possible.

Make sure closed captioning is available

Closed captioning or transcripts should be available for all videos. The information presented in videos should also be available in other formats.

Be mindful of visual elements

Aim for high contrast between your font and background colors. Tools in the resources section should help with picking accessible colors.

Images should not be the only method of communication, because images may not load or may not be seen. Avoid using images when the same information could be communicated in writing.

CCF serves hundreds of countries and territories, not just the United States. As the diagnosis of cholangiocarcinoma increases, our user base grows, and it becomes more important that our content and resources are accessible to people around the world.

We call the process of writing copy for translation “internationalization.” This section will addresses what we do to help international audiences, including translators, better comprehend our text.

Basics

Select content is available to all users in English, Spanish, and Korean. Sometimes other pieces of content will be translated as well.

We try to write all of our content in standard, straightforward English that can be understood by users with limited English proficiency. It’s much easier for a translator to clearly communicate ideas written in straightforward, uncomplicated sentences.

Here are some guiding principles for writing for international audiences:

• Use active voice. We always aim for this, but it’s especially important when writing for translation.
• Use the subject-verb-object sentence structure. It’s not used by all languages, but it’s widely recognized.
• Use positive words when talking about positive situations. For example, because a question like “Don’t you think she did a great job?” begins with a negative word, a non-native English speaker may interpret its implication as negative. A better version would be “She did a good job, right?”

Guidelines

If we’re writing something to be translated, the guidelines in this section take precedence.

Consider cultural differences

CCF’s voice is conversational but formal. However, in some cultures, formal text may be considered offensive. We check with translators to see if this is the case for particular language we may be writing.

The translation company should give the option to translate in a formal or informal tone, if the language allows for it. (For example, in Spanish, it is possible to write informally where tú = you or formally where usted = you.)

When writing text that will be translated, we are careful about making references to things of local or regional importance. These may not be recognizable to readers outside the US.

Avoid ambiguity and confusion

Many words, parts of speech, and grammar mechanics we don’t think twice about have the potential to cause confusion for translators and non-native English speakers. Here are some of the big trouble spots to avoid.

Avoid unclear pronoun references

• Yes: Many believe that buying a list of email addresses and sending to the list through Mailchimp is OK. Such action can actually cause high rates of abuse, bounces, and unsubscribes. Purchasing a list and sending to it may cause your account to be suspended.
• No: Many believe that buying a list of email addresses and sending to the list through Mailchimp is okay. This can actually cause high rates of abuse, bounces, and unsubscribes. It can ultimately cause your account to be suspended.

Avoid -ing words

In English, many different types of words end in -ing: nouns, adjectives, progressive verbs, etc. But a translator who is a non-native English speaker may not be able to recognize the distinctions and may try to translate them all in the same way.

Because of this, we want to avoid -ing words when possible. One exception to this rule is words like “graphing calculator” and “riding lawnmower,” where the -ing word is part of a noun’s name and can’t be worked around.

Here are some other cases where you might see -ing words, and suggestions for how to edit around them.

Gerunds

• Yes: In this article we will talk about list subscriber collection.
• No: In this article we will talk about getting list subscribers.

Adjectives

• Yes: At the top of the page, there is Freddie with a smile on his face.
• No: At the top of the page, there is a smiling Freddie.

Parts of verbs

• Yes: Several developers are currently working on that feature.
• No: Several developers are working on that feature. (When you can’t easily avoid the -ing word, it may help to add an adverb to clarify the meaning.)

Parts of phrases modifying nouns:

• Yes: From our backyard, we could hear the planes that took off from the airport.
• No: From our backyard, we could hear the planes taking off from the airport.

Other words and mechanics to avoid

• Slang, idioms, and cliches
• Shortened words, even if they’re common in English (use “application,” not “app”)
• Uncommon foreign words (use “genuine,” not “bona fide”)
• Unnecessary abbreviations (use “for example,” not “e.g.”)
• Converting one part of speech into another if it isn’t already commonly used (use “Send us an email” instead of “message us”)
• Non-standard or indirect verb usage (use “he says,” not “he’s like” or “he was all”)
• Double negatives
• Synonyms, generally. Don’t use a lot of different words for the same thing in a single piece of writing. Instead of mixing it up with “campaign,” “newsletter,” “bulletin,” etc., pick one term and stick with it.

Beware words with multiple meanings

“Once” (could mean “one time,” “after,” “in the past,” or “when”) – Yes: After you log in, you will see your account’s Dashboard. – No: Once you log in, you will see your account’s Dashboard.

“Right” (could mean “correct,” “the opposite of left,” “politically conservative,” etc.)

• Yes: In the File Manager, click the correct image and drag it to the pane at right.
• No: In the File Manager, click the right image and drag it to the right pane.

“Since” (could refer to a point in time, or a synonym of “because”)

• Yes: Because you already have a complete mailing list, you can send your campaign at any time.
• No: Since you already have complete mailing list, you can send your campaign at any time.

“Require” plus an infinitive (could confuse the relationship between subject and object)

• Yes: Autoresponders can be configured and sent from paid accounts.
• No: A paid account is required to send autoresponders. (This could imply that users with paid accounts are required to send autoresponders.)

“Has” or “have” plus past participle (could confuse the relationship between subject and object)

• Yes: The folder contains sent campaigns.
• No: The folder has sent campaigns.

Numbers

Measurements

When writing for an international audience, use the metric system. Spell out all units and avoid abbreviation.

Currency

Many countries call their currency “the dollar,” but the value is going to differ between countries. The US dollar is not the same as the Canadian dollar, for example. So it’s important to specify.

Indicate currency by using its 3-letter abbreviation, such as USD or CAD. Don’t use currency symbols, like $ or €. We would say 25 USD, not $25.

Avoid colloquial phrases that relate to money, like “five-and-dime,” “greenbacks,” or “c-notes.” These won’t translate well.

At CCF, we write two (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.

Basics

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

All educational content at Mailchimp relies heavily on content templates. We use templates for Technical Content, Integration Directory descriptions, marketing guides, and more.

Guidelines

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 two (2) main ways to approach this.

Use a model

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:

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

Start from scratch

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.

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.

Basics

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.

Copyright notice on the work is not required but it is recommended, since it cuts off a defense of innocent infringement.

Copyright at CCF

Copyright law applies to nearly every piece of content we create at CCF, from our website to our blog posts. We display proper—and prominent—copyright notice on our website site and any other content we produce.

At minimum, these copyright notices read, “© [YEAR] Cholangiocarcninoma Foundation.”

At the bottom of every page of our website, we also include a longer notice to make it clear that all rights are reserved and our marks are registered: “© 2021 All Rights Reserved.”

Other creators’ copyrights

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 Cholangiocarcinoma Foundation 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.”

If you need to get a copyright license for work at CCF or if someone outside of CCF asks to use our copyrighted work, please contact the executive team.

Social media and copyright

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 CCF is a nonprofit, 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 CCF 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.

Image use and copyright

CCF almost always uses original images in our blog posts. If you use an image, photo, or other design element made by someone outside CCF, 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.

Other licenses

Creative Commons licenses

Instead of the standard “all rights reserved,” some creators choose to make their work available for public use with different levels of attribution required.

Please check with CCF’s Communication team before making something you created here available under a Creative Commons license. We love to share our work, but we use these licenses sparingly, because we have to protect our intellectual property and trade secrets.

Trademarks

A trademark, often called a mark, can be a word, name, sign, design, or a combination of those. It’s used to identify the provider of a particular product or service. They’re usually words and images, but in some cases, they can even be a color.

To be protectable, a trademark needs a distinctive element. There’s a “spectrum of distinctiveness” that spans from inherently protectable marks to ones that require additional proof to ones that may never be protected.

• Fanciful marks, which are made up words like Kodak or Xerox, are the most easily registered and protected.
• Arbitrary marks, which are words which are used out of context like Apple or Sprite, are also easy to protect.
• Suggestive marks, which suggest at some element of the goods or services like Greyhound, follow.
• Descriptive marks, where the word’s dictionary meaning aligns with the goods or services offered, like Mr. Plumber or Lektronic, are not protectable unless they develop a secondary meaning. That means a consumer would immediately associate the mark with only that good or service. This can be hard to prove, so it’s best to avoid descriptive marks when possible.
• Generic terms, or the common name for a product or service, are not protectable.

We usually classify CCF as a descriptive mark. A trademark is only valid for as long as it indicates the source of that good or service, so we have to be very careful about how our marks are used. We send out cease and desist letters sometimes, because even the friendliest companies have to protect their trademarks. If a trademark is properly protected, it can last forever and may be a company’s most valuable asset.

Displaying trademark notices

To note that something is a trademark, and in the case of registered marks in order to collect damages, the trademark has to be displayed with an appropriate symbol.

Here are the various trademark symbols and when to use them:

• For unregistered trademarks of goods, use ™
• For unregistered trademarks of services, use ℠
• For trademarks granted registration by the United States Patent and Trademark Office, use ®
• Note that using ® on marks that haven’t been registered by the USPTO can be considered fraud, so if you’re not sure if a trademark is registered, don’t use ®

The trademark symbol should appear as close to the mark as possible.

Here’s how to indicate CCF’s trademark:

• Include the ® symbol in the upper right-hand corner, above the word: Mailchimp® this use is preferable.
• Include the ® symbol in the lower right-hand corner, below the word: Mailchimp®

Marks are also sometimes indicated by using all caps: CCF

Our trademarks should be properly noted the first time they’re used in a press release or article, or anywhere else our trademark and copyright notice does not appear.

Registering trademarks at CCF

We register all of our trademarks. Before we decide to use a name for a project, we perform a trademark search to make sure there aren’t any confusingly similar trademarks already in use.

For the most part, our trademarks are “suggestive marks,” which mean the name suggests at some element of the goods or services represented.

If you’re a CCF volunteer, submit name possibilities to the Communication Team so it can get a head start on the trademark search. Even if you haven’t used the name yet, we can go ahead and file an Intent to Use application.

CCA
Cholangiocarcinoma

CCF
Cholangiocarcinoma Foundation

IC
Industry Council

ICRN
International Cholangiocarcinoma Research Network

• a program of CCF – 38 US members/institutions and 31 Int’l institutions
• Industry Forum – ICRN members meet with industry members at the CCF annual conference

SMAB
Scientific and Medical Advisory Board – a program of CCF

CCA²
Cholangiocarcinoma Common Control Arm

• a program with 3 of the members of the IC & FDA – CCF is an honest broker between the FDA and these three companies.

PAB
Patient Advisory Board

NAB
Nursing Advisory Board