-
Notifications
You must be signed in to change notification settings - Fork 15
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Draft content styleguide #3133
Draft content styleguide #3133
Conversation
|
||
## 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." |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Should GSA
be the U.S. General Services Administration (GSA)
? or should it be called out as an exception to the rule above?
Co-authored-by: Ben Berry <[email protected]> Signed-off-by: Sarah Rudder <[email protected]>
|
||
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 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Why did contractions, abbreviations, and statements v. questions get the axe?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
YESSSSS!!
Thank you for codifying and writing this down!
This is a fabulous update, and will help to bring others into writing consistently (on cg-site, when emailing customers, in preso decks) with a "Cloud.gov" voice.
Changes proposed in this pull request:
Adds much more detail and standardizes some voice and tone
security considerations
n/a unless we want to add some security language