Draft content styleguide

ContentGuide.md

@@ -1,19 +1,188 @@
-# Make cloud.gov words consistent
+# Cloud.gov Voice & Tone Content Style Guide
+
+Jump to:
+- **[How to sound like Cloud.gov](#how-to-sound-like-cloudgov)**
+    1. [Be clear and direct](#1-be-clear-and-direct)
+    2. [Be trustworthy and knowledgeable](#2-be-trustworthy-and-knowledgeable)
+    3. [Be proactive and helpful](#3-be-proactive-and-helpful)
+    4. [Use the right tone](#4-use-the-right-tone)
+- **[How to talk about Cloud.gov](#how-to-talk-about-cloudgov)**
+    1. [Keep it simple](#1-keep-it-simple)
+    2. [Look for a contrast](#2-look-for-a-contrast-from-the-expected)
+    3. [Focus on the customer's perspective](#3-focus-on-the-customers-perspective)
+- **[How to talk about Cloud.gov Pages](#how-to-talk-about-cloudgov-pages)**
+- **[How to talk about everyone else](#how-to-talk-about-everyone-else)**
+    1. [Referring to other offices, programs, or teams within TTS or GSA](#1-referring-to-other-offices-programs-or-teams-within-tts-or-gsa)
+    2. [Referring to external or non-government entities](#2-referring-to-external-or-non-government-entities)
+- **[How to write like Cloud.gov](#how-to-write-like-cloudgov)**
+    1. [Use good content structure and formatting.](#1-use-good-content-structure-and-formatting)
+    2. [Use consistent spelling, capitalization, punctuation, and spacing](#2-use-consistent-spelling-capitalization-punctuation-and-spacing)
+- **[How to write documentation for Cloud.gov](#how-to-write-documentation-for-cloudgov)**
+    1. [Keep roles consistent](#1-keep-roles-consistent)
+    2. [Customer responsibilities](#2-customer-responsibilities)
+* * * * *
+
+
+## How to sound like Cloud.gov
+
+Use the principles of **voice** and **tone** to craft your messaging. 
+
+**Voice** is _consistent_ across all communications, reflecting a helpful, knowledgeable, and trustworthy partner. This is the foundation of how we present ourselves to users, stakeholders, and the public. Our voice sounds:
+
+1.   **Clear and direct** 
+2.   **Trustworthy and knowledgeable** 
+3.   **Proactive and helpful** 
+
+While the voice remains consistent, our **tone** adapts based on the audience and the message. 
+For example:
+
+-   **Direct support** sounds personalized and formal
+-   **Internal collaboration** sound personalized and informal
+-   **Technical documentation** sounds generalized and formal
+-   **Announcements and marketing** sounds generalized and informal
+
+* * * * *
+
+### 1\. Be clear and direct: 
+- Use [easy-to-understand language](https://www.plainlanguage.gov/guidelines/words/use-simple-words-phrases/) and [clarify acronyms](https://www.plainlanguage.gov/guidelines/words/minimize-abbreviations/), [complex instructions](https://www.plainlanguage.gov/guidelines/words/place-words-carefully/), and [unfamiliar terms](https://www.plainlanguage.gov/guidelines/words/minimize-definitions/). 
+- ~~If you can say something in fewer words, do so.~~ [Shorter is better.](https://www.plainlanguage.gov/guidelines/concise/)
+- Don't assume you have undivided attention; it's much more likely that your reader is distracted or in the middle of something. For their sake, make your content [easy to scan and digest](https://www.plainlanguage.gov/guidelines/concise/write-short-sections/). 
+- [Address the user](https://www.plainlanguage.gov/guidelines/audience/address-the-user/) to make it clear who the message is intended for.
+- At all costs, [avoid the passive voice](https://www.plainlanguage.gov/guidelines/conversational/use-active-voice/) — make it clear _who_ is responsible for _what_.
+
+> ~~"Official ATU documentation must be provided before production use is authorized."~~
+
+>  "Make sure you send us a copy of your ATU letter, signed by your agency security leader, before you launch. Using Pages for production sites without a signed ATU violates your customer agreement."
+<details>
+<summary><b>Why use active voice?</b>
+</summary>
 
-Do you ever write cloud.gov outage updates, dev docs, compliance docs, or other words about cloud.gov? Do you want to...
+Use active voice, especially when you're writing technical explanations. For example: *"the subject did something"*, such as *"the cluster recorded the data"*.
+
+If you write sentences in passive voice (*"something was done"*, such as *"the data was recorded"*), your sentence is hiding important technical information: what did the action? What recorded the data? If you start to write *"**something** was done by the **thing**"*, revise it to say *"the **thing** did **something**"*.
+
+Using active voice is important for outage reports and postmortems. If we write with passive voice, this can sound like we're not taking full responsibility for our actions and mistakes.
+
+Active voice is also important for documentation (including compliance documentation). When you state which part of the system is doing which action, this helps readers understand how the system works.
+</details>
+
+### 2\. Be trustworthy and knowledgeable:
+- Cloud.gov values our relationship with our users and the trust they place in our platform. We earn that trust by using work-appropriate, accessible, and inclusive language. 
+- Be approachable without becoming unprofessional by incorporating context, clarifying expectations, and demonstrating respect.
+- Neither over- nor under-promise; instead, [consistently](https://www.plainlanguage.gov/guidelines/words/use-the-same-terms-consistently/) present a composed, intentional, and reassuring message with integrity. 
+- Don't try to sound smart when you can just as easily ELI5.
+
+
+> ~~"Utilize the resources provided to ensure adherence to compliance."~~
+
+>"Use [this template](#) to help you meet the compliance standards outlined in OMB's M-23-22."
+
+### 3\. Be proactive and helpful:
+- Our customers may feel like they're working in isolation, but we see the patterns that emerge across hundreds of federal apps and websites. Cloud.gov puts these lessons in practice for our users. 
+- Encourage users by [presenting options and solutions](https://www.plainlanguage.gov/guidelines/concise/use-positive-language/) rather than [focusing on limitations or exceptions](https://www.plainlanguage.gov/guidelines/organize/place-the-main-idea-before-exceptions-and-conditions/). 
+- If what you need to communicate is hard to understand without prerequisite knowledge, explain or link to that information -- you're probably better suited to find a good source than your reader. 
+- [Soften transitions](https://www.plainlanguage.gov/guidelines/organize/use-transition-words/) to prevent losing attention or context at key intersections.
+- Own the responsibility for making sure our customers have what they need before they even go to reach for it, so our users can focus on their mission instead of ours.
+
+> ~~"You can only use preview links for changes on branches other than main. Main is for production use only."~~
+
+> "Most customers end up wanting a consistent staging URL where they can preview all recent changes before they go live. Here's how you can set up a demo site at a particular domain in just a few steps."
+
+* * * * *
+
+### 4\. Use the right tone
+
+-   **Formal vs. Informal**: Match the tone to the context. A more formal tone is used for legal, compliance, or regulatory documentation, while informal tone suits emails or customer engagement platforms like Slack. 
+
+    -   **Formal**: "To comply with OMB M-23-22, agencies must follow the outlined guidelines."
+    -   **Informal**: "We're excited to announce new features that simplify your compliance process!"
+
+-   **Generalized vs. Personalized**: When individual users encounter difficulties (e.g., compliance challenges), the tone should be helpful and supportive. Take care not to become patronizing by speaking down to customers or assuming ignorance, particularly with diverse audiences.
+
+    -   **Generalized**: "We know that maintaining compliance can be tough, particularly for small teams. That's why we've provided easy-to-follow guides to help you stay on track."
+    -   **Personalized**: "I can see how this process seems overwhelming. Let's walk you through the process step by step."
+
+
+| Context | Tone  | Example |
+| -- | --- | --- |
+| **Website and Blog Post** | Informal, generalized, informative, and solution-oriented. | "Need help getting started with Cloud.gov? Our step-by-step guide will walk you through setting up your account." |
+| **Technical Documentation** | Formal, generalized, informative, and efficient. | "To create an account, fill out the required fields and click 'Submit.' For detailed instructions, see our account setup guide." |
+| **Customer Support (Slack, Email)** | Informal, personalized, and encouraging. | "Thanks for reaching out! We're here to help you resolve this quickly. Let's take a look at what's happening with your site." |
+
+* * * * *
+
+## How to talk about Cloud.gov
+When you speak or write on behalf of Cloud.gov:
+
+### 1\. Keep it simple.
+Compliance and infrastructure is hard enough. Use approachable terms and simple sentences whenever you can:
+-   "Cloud.gov helps government agencies buy, build, and authorize modern cloud services."
+-   "Cloud.gov is a shared cloud computing service that helps agencies deliver websites and web applications securely, so they can do their real work."
+
+### 2\. Look for a contrast from the expected.
+Double down on what makes Cloud.gov unique. Slow and difficult software projects are the norm, but **getting to delivery is surprisingly fast and easy with Cloud.gov:**
+-   "All you need is a federal email address — no paperwork, no hassle."
+-   "Reduce time to ATO and get applications to market faster"
+-   "Baked-in security and scalability allows agencies to move quickly"
+
+Federal contracting and compliance is a headache, but **we get federal, because we _are_ federal:**
+-   "Instead of a multi-month RFP and bid cycle, your hosting is a simple MOU or IAA away."
+-   "With Cloud.gov’s position, context, and expertise inside government, we understand firsthand what’s hard for agency customers."
+-   "One of our early goals for Cloud.gov was to give other agencies access to the same gains in productivity that 18F and other parts of TTS have seen from using Cloud.gov."
+
+Technology teams usually spend months on configuration and compliance before they even get to the real application development. That's why **we make stability and security our mission, so you can focus on yours:**
+-   "Build the _right_ thing, not _everything_."
+-   "We do _more_ so that agencies are responsible for _less_."
+-   "You don't have to build your tech from the ground up."
+-   "Employees and contractors can focus on developing mission-critical applications, leaving server infrastructure management to us."
+-   "We’re here to help federal agencies accomplish their mission faster, easier, and with less friction."
+-   "Government agencies have a mission to accomplish — and most of the time, technology itself isn’t the mission."
+
+### 3\. Focus on the customer's perspective.
+Wherever possible, center the messaging around our customers and their use cases and needs, rather than our platform, offerings, or services:
+
+-   "Cloud.gov customers focus on mission, instead of struggling with technology contracts, hiring, and regulatory compliance."
+-   "Cloud.gov customers significantly reduce risk by running on an environment built and scaled for the federal cybersecurity and regulatory ecosystem."
+-   "Cloud.gov customers access volume-priced cloud services through hassle-free interagency agreements to get the most value for the money."
 
-* ...write helpful info that helps our readers trust us?
-* ...never wonder again how to capitalize cloud.gov, BOSH, or GitHub?
 
-OK, follow this guide!
+## How to talk about Cloud.gov Pages
+Coming soon!
 
-Consistency helps cloud.gov look trustworthy and reliable, and it reduces potential reader confusion.
+ * * * * *
 
-**You should add things too:** Just make a pull request.
+## How to talk about everyone else
 
-For additional helpful background knowledge about writing for cloud.gov users, see the [18F Content Guide](https://pages.18f.gov/content-guide/), including its [content principles](https://pages.18f.gov/content-guide/content-principles/).
+### 1\. Referring to other offices, programs, or teams within TTS or GSA
 
-## Use these exact strings for tricky product names, abbreviations, and team names
+-   **Assume everyone is drowning in alphabet soup**: Always use full names on first reference, before using acronyms, except for messages to other TTS audiences. For now, it's usually less relevant to mention that we're within Solutions or FAS.
+    >   "Cloud.gov, part of the Technology Transformation Services (TTS) within GSA, supports federal agencies build secure, resilient web applications."
+
+-   **Be transparent and collaborative**: Emphasize teamwork and shared goals, and share the limelight. Be a good neighbor.
+    >   "We're proud of our colleages at 18F who worked on this prototype, which was powered by Cloud.gov."
+
+### 2\. Referring to external or non-government entities
+
+-   **Always visually distinguish external links** and comply with [GSA's external linking policy](https://www.gsa.gov/website-information/website-policies#:~:text=We%20provide%20these%20links%20as,included%20in%20these%20website%20links.)
+
+-   **Commit to reviewing any external link annually**: Webpages move or change over time, and rarely with notice. Before you refer customers to other sources, consider whether the content will still be as relevant in a year. It may be more appropriate to link to a canonical version.
+
+-   **Prefer official standards bodies and other government agency resources**: Only include external links when they provide direct value to the user and align with Cloud.gov's values (e.g., accessibility, security). External links should be from reputable sources like standards bodies or other government websites.  If you must link to a specific resource maintained by someone other than a government agency or standards body, prefer open source, community-maintained repo or documentation links. 
+
+-   **Do not imply an endorsement**: Hyperlinks to non .gov or standards websites should be exceedingly rare, and when they are used, should be clearly marked as an external link and marked `rel="noreferrer noopener"`. This attribute indicates to browsers and SEO engines that this is an untrusted link. External links from a .gov website can greatly influence the search result ranking of a domain, which could be interpreted as an advantage to a given vendor. It is not necessary to directly credit a vendor or company for their participation in paid work or open source contributions.
+
+
+
+* * * * *
+## How to write like Cloud.gov
+
+### 1\. Use good content structure and formatting.
+-   **Design for reading**: [Per the Plain Language guidelines](https://www.plainlanguage.gov/guidelines/design/), structure your content so that it's easy to read
+-   **Headings**: [Add useful headings](https://www.plainlanguage.gov/guidelines/organize/add-useful-headings/) to help readers scan content quickly. Prefer sentence case to Title Case, and only end a title with a period if it's a complete sentence.
+-   **Prose**: [Have a topic sentence](https://www.plainlanguage.gov/guidelines/organize/have-a-topic-sentence/) that concisely makes your point. Always start with the most important information first. [Use bullet points or numbered lists](https://www.plainlanguage.gov/guidelines/organize/use-lists/) to break down complex ideas.
+-   **Linking**: Provide context for all links and [use descriptive anchor text](https://www.plainlanguage.gov/guidelines/web/write-effective-links/) that reflects the linked content.
+
+### 2\. Use consistent spelling, capitalization, punctuation, and spacing
 
 Use these exact strings (keeping this spelling, capitalization, punctuation, and spacing):
 
@@ -27,7 +196,7 @@ Use these exact strings (keeping this spelling, capitalization, punctuation, and
 * **ClamAV**
 * **Cloud Controller**
 * **Cloud Foundry**
-* **cloud.gov** (always lowercase, except at the beginning of a sentence or as part of a subproduct name, e.g. **Cloud.gov Pages**)
+* **Cloud.gov** (always capitalized, fix it where you see it lowercase)
 * **Cloudability**
 * **CloudFront**
 * **CloudTrail**
@@ -72,8 +241,6 @@ Use these exact strings (keeping this spelling, capitalization, punctuation, and
 * **YAML**
 * **Zendesk**
 
-## Use these non-case-sensitive strings for words with tricky spacing and punctuation
-
 These words should be lowercased in the middle of a sentence and capitalized at the beginning of a sentence, but use this exact spacing and punctuation.
 
 * **email**
@@ -88,44 +255,18 @@ These words should be lowercased in the middle of a sentence and capitalized at
 * **timestamp**
 * **website**
 
-## Use active voice instead of passive voice
-
-Use active voice, especially when you're writing technical explanations. For example: *"the subject did something"*, such as *"the cluster recorded the data"*.
-
-If you write sentences in passive voice (*"something was done"*), such as *"the data was recorded"*, your sentence is hiding important technical information: what did the action? What recorded the data? If you write *something was done by the thing*, revise it to say *the thing did something*.
-
-Using active voice is important for outage reports and postmortems. If we write with passive voice, this can sound like we're not taking full responsibility for our actions and mistakes.
-
-Active voice is also important for documentation (including compliance documentation). When you state which part of the system is doing which action, this helps readers understand how the system works.
-
-## Use contractions and friendly language
-
-Use contractions. Write ordinary straightforward explanations; rewrite stiff or formal phrasing.
-
-## Spell out abbreviations and acronyms early and often
-
-Spell out abbreviations and acronyms the first time you use a term on a page or in a section of a long document.
-
-If you're not sure whether an acronym or abbreviation is a first use (such as if you're writing a section in YAML to use with Compliance Masonry), spell it out. There's no harm in writing out abbreviations an extra time; it'll make up for all the government documents everywhere that have too many unexplained abbreviations.
-
-## Phrase titles as statements instead of questions
-
-Also known as: **How should you phrase titles?**
-
-When you're writing a title for a page or section, write a statement instead of a question. Those extra "who/what/why" words aren't necessary, and statements are easier for readers to scan quickly.
-
-## Compliance documentation
 
-*This section is a work in progress.*
+* * * * *
 
-### Keep roles consistent
+## How to write documentation for Cloud.gov
 
+### 1\. Keep roles consistent
 Capitalize roles throughout the document to help readers understand that you're talking about specific roles rather than just groups of people in general. For example, "Authorizing Official", "Cloud Operations", and "Information Systems Security Officer".
 
 In control descriptions (under "Responsible Roles"):
 * List roles with commas, for example "System Owner, Cloud Operations". Don't include "and".
 * List roles that can be singular, such as "Authorizing Official", as singular (even if the actual role is occupied by multiple people).
 
-### Customer responsibilities
+### 2\. Customer responsibilities
 
 Write “**Customer Responsibility**” in bold whenever we want to indicate that something is a customer responsibility (not “Client Application” or other titles).