Jump to:
- How to sound like Cloud.gov
- How to talk about Cloud.gov
- How to talk about Cloud.gov Pages
- How to talk about everyone else
- How to write like Cloud.gov
- How to write documentation for 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:
- Clear and direct
- Trustworthy and knowledgeable
- 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
- Use easy-to-understand language and clarify acronyms, complex instructions, and unfamiliar terms.
If you can say something in fewer words, do so.Shorter is better.- 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.
- Address the user to make it clear who the message is intended for.
- At all costs, avoid the passive 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."
Why use active 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 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.
- 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 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."
- 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 rather than focusing on limitations or exceptions.
- 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 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."
-
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." |
When you speak or write on behalf of Cloud.gov:
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."
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."
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."
Coming soon!
-
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."
-
Always visually distinguish external links and comply with GSA's external linking policy
-
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.
- Design for reading: Per the Plain Language guidelines, structure your content so that it's easy to read
- Headings: 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 that concisely makes your point. Always start with the most important information first. Use bullet points or numbered lists to break down complex ideas.
- Linking: Provide context for all links and use descriptive anchor text that reflects the linked content.
Use these exact strings (keeping this spelling, capitalization, punctuation, and spacing):
- 18F
- AIDE
- Amazon Web Services (or AWS)
- AWS Config
- BOSH
- CircleCI
- CF CLI
- ClamAV
- Cloud Controller
- Cloud Foundry
- Cloud.gov (always capitalized, fix it where you see it lowercase)
- Cloudability
- CloudFront
- CloudTrail
- CloudWatch
- Code Climate
- Concourse
- Docker
- EC2
- ElastiCache
- Elasticsearch
- ELK
- Jira
- FedRAMP
- FISMA levels are Low, Moderate (not Medium), and High.
- Git
- GitHub
- GovCloud
- Grafana
- Information Systems Security Officer (or ISSO)
- Information Systems Security Manager (or ISSM)
- Infrastructure as a Service (or IaaS)
- iptables
- JSX
- Kibana
- Loggregator
- Logstash
- Nessus
- New Relic
- OAuth
- OWASP ZAP
- Platform as a Service (or PaaS)
- React (when talking about the library)
- Redis
- Riemann
- Roles use the same word choice and capitalization as the CF CLI, with spaces for clarity: Org Manager, Billing Manager, Org Auditor, Space Manager, Space Developer, Space Auditor.
- StatusPage
- Travis CI
- Trusted Advisor
- Virtual Private Cloud
- VisualOps
- WebInspect
- YAML
- Zendesk
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.
- dashboard (our web user interface, formerly Deck or Console)
- federal
- internet
- jumpbox
- one-time authentication code (this is good to use instead of one time code or one-time registration code)
- role-based access control
- stemcell
- third-party credentials
- timestamp
- website
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).
Write “Customer Responsibility” in bold whenever we want to indicate that something is a customer responsibility (not “Client Application” or other titles).