Draft content styleguide #3133
Merged
Draft content styleguide #3133
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
sknep
requested review from
jameshochadel,
kfoley-18F,
wz-gsa,
nicki-wilson,
pburkholder and
bengerman13
bengerman13
reviewed
Sep 20, 2024
bengerman13
reviewed
Sep 20, 2024
|
|
||
| ## 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.
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 <ben.berry@gsa.gov> Signed-off-by: Sarah Rudder <sknep@users.noreply.github.com>
pburkholder
reviewed
Sep 23, 2024
|
|
||
| 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.
Why did contractions, abbreviations, and statements v. questions get the axe?
kfoley-18F
approved these changes
Sep 24, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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