Skip to content

Commit 005cd87

Browse files
natalialuzuriaganatalialuzuriaga
authored
Merge pull request #211 from DSACMS/natalia/comms-guide
Outbound Checklists: Added Communications Style Guide
2 parents fd6c255 + 28f7eec commit 005cd87

15 files changed

+131
-18
lines changed

‎.github/workflows/checklistMarkdownToPDF.yml

+4-2
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ on:
44
types: [opened, synchronize]
55
# Paths can be used to only trigger actions when you have edited checklist files
66
branches:
7-
- 'checklists/**'
7+
- 'dev'
88
paths:
99
- 'tier*/checklist.md'
1010

@@ -24,13 +24,15 @@ jobs:
2424
uses: tj-actions/changed-files@v45
2525
with:
2626
dir_names: "true"
27+
dir_names_include_files: 'checklist.md'
2728
- name: List all changed tier directories
2829
id: list-dirs
2930
env:
3031
ALL_CHANGED_FILES: ${{ steps.get-dirs.outputs.all_changed_files }}
3132
run: |
3233
# Obtain changed tier directories and format into array
33-
DIRS=$(echo "$ALL_CHANGED_FILES" | grep -oE 'tier[^ ]*' | sed 's/^/"/; s/$/"/' | paste -sd, -)
34+
DIRS=$(echo "$ALL_CHANGED_FILES" | grep -oE 'tier[1-4]'| grep -oE 'tier[^ /]*' | sort -u | sed 's/^/"/; s/$/"/' | paste -sd, -)
35+
echo "$DIRS"
3436
3537
# Output the array
3638
TIER_DIRS="[$DIRS]"

‎README.md

+9
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,15 @@ this question - `"project_name": "My Project",`. See the [cookiecutter docs](ht
4545
for more information.
4646

4747
## Repolinter
48+
49+
Repolinter is a tool maintained by the [TODOGroup](https://todogroup.org/) for checking repositories for common open source issues, using pre-defined rulesets. This can be run stand-alone as a script, pre-commit in your IDE, or post-commit or within CI/CD systems!
50+
51+
✔    =  Pass
52+
53+
✖    =  Fail
54+
55+
⚠  =  Warn
56+
4857
Tiers of level 1 thru 4 have repolinter.json file in their projects. Tier1 has detailed configuration of all the rules. All the other tiers extends their previous tiers and has only the `rule` and the `level` configuration.
4958

5059
Sample commands to run with the given repolinter.json path:

‎tier0/hooks/post_gen_project.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -8,9 +8,6 @@
88
RECEIVE_UPDATES = '{{cookiecutter.receive_updates}}'
99

1010
def createGithubRepo():
11-
subprocess.call(["git", "init", "-b", "main"])
12-
subprocess.call(["git", "add", "."])
13-
subprocess.call(["git", "commit", "-m", "first commit"])
1411
gh_cli_command = [
1512
"gh", "repo", "create",
1613
f"{ORG_NAME}/{REPO_NAME}",
@@ -30,6 +27,10 @@ def addTopic():
3027
]
3128
subprocess.call(gh_cli_command)
3229

30+
subprocess.call(["git", "init", "-b", "main"])
31+
subprocess.call(["git", "add", "."])
32+
subprocess.call(["git", "commit", "-m", "initial commit"])
33+
3334
if CREATE_REPO == "True":
3435
createGithubRepo()
3536

‎tier1/checklist.md

+25-1
Original file line numberDiff line numberDiff line change
@@ -192,7 +192,7 @@ repolinter lint .
192192
3. The results produces an issue on the repository with a list of file and section existence checks, indicating whether each requirement was met or not
193193

194194

195-
**Review Content**
195+
#### Review Content
196196

197197
The project should include the following files and sections [(link to template)](https://github.com/DSACMS/repo-scaffolder/tree/main/tier1/%7B%7Bcookiecutter.project_slug%7D%7D):
198198

@@ -237,6 +237,30 @@ repolinter lint .
237237

238238
*Contains metadata about the project, refer to [Review Project Metadata](#review-project-metadata)*
239239

240+
#### Communications Style Guide
241+
242+
As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
243+
244+
- **Focus on solutions, not problems**
245+
_Rather than describing the negatives and shortcomings of an existing project, process, or group, focus on highlighting the benefits, outcomes, and positive impacts of the solution. Be constructive and accentuate the positive._
246+
247+
- **Use Plain Language**
248+
_Be clear and concise when explaining concepts. Avoid jargon unless it is necessary and well-defined. Use active voice to be clearer and more engaging._
249+
250+
- **Focus on the audience**
251+
_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
252+
253+
Please refer to the style guides below for additional tips and guidance:
254+
255+
- CMS Resources
256+
- [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
257+
- [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
258+
- [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
259+
260+
- [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
261+
262+
- [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
263+
240264
#### Results
241265
*Insert Review Here*
242266

‎tier1/checklist.pdf

13.8 KB
Binary file not shown.

‎tier1/hooks/post_gen_project.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,6 @@
1010
RECEIVE_UPDATES = '{{cookiecutter.receive_updates}}'
1111

1212
def createGithubRepo():
13-
subprocess.call(["git", "init", "-b", "main"])
14-
subprocess.call(["git", "add", "."])
15-
subprocess.call(["git", "commit", "-m", "first commit"])
1613
gh_cli_command = [
1714
"gh", "repo", "create",
1815
f"{ORG_NAME}/{REPO_NAME}",
@@ -43,6 +40,10 @@ def moveCookiecutterFile():
4340
shutil.move(source_path, destination_path)
4441

4542
def main():
43+
subprocess.call(["git", "init", "-b", "main"])
44+
subprocess.call(["git", "add", "."])
45+
subprocess.call(["git", "commit", "-m", "initial commit"])
46+
4647
if CREATE_REPO == "True":
4748
createGithubRepo()
4849

‎tier2/checklist.md

+25
Original file line numberDiff line numberDiff line change
@@ -281,6 +281,31 @@ The project should include the following files and sections [(link to templates)
281281

282282
*Lists project maintainers and their responsibilities*
283283

284+
#### Communications Style Guide
285+
286+
As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
287+
288+
- **Focus on solutions, not problems**
289+
_Rather than describing the negatives and shortcomings of an existing project, process, or group, focus on highlighting the benefits, outcomes, and positive impacts of the solution. Be constructive and accentuate the positive._
290+
291+
- **Use Plain Language**
292+
_Be clear and concise when explaining concepts. Avoid jargon unless it is necessary and well-defined. Use active voice to be clearer and more engaging._
293+
294+
- **Focus on the audience**
295+
_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
296+
297+
Please refer to the style guides below for additional tips and guidance:
298+
299+
- CMS Resources
300+
- [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
301+
- [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
302+
- [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
303+
304+
- [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
305+
306+
- [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
307+
308+
284309

285310
#### Results
286311
*Insert Review Here*

‎tier2/checklist.pdf

14.1 KB
Binary file not shown.

‎tier2/hooks/post_gen_project.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,6 @@
1111
ADD_MAINTAINER = '{{cookiecutter.add_maintainer}}'
1212

1313
def createGithubRepo():
14-
subprocess.call(["git", "init", "-b", "main"])
15-
subprocess.call(["git", "add", "."])
16-
subprocess.call(["git", "commit", "-m", "first commit"])
1714
gh_cli_command = [
1815
"gh", "repo", "create",
1916
f"{ORG_NAME}/{REPO_NAME}",
@@ -84,6 +81,10 @@ def moveCookiecutterFile():
8481
shutil.move(source_path, destination_path)
8582

8683
def main():
84+
subprocess.call(["git", "init", "-b", "main"])
85+
subprocess.call(["git", "add", "."])
86+
subprocess.call(["git", "commit", "-m", "initial commit"])
87+
8788
if CREATE_REPO == "True":
8889
createGithubRepo()
8990

‎tier3/checklist.md

+24
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,30 @@ The project should include the following files and sections [(link to templates)
321321

322322
*Contains metadata about the project, refer to [Review Project Metadata](#review-project-metadata)*
323323

324+
#### Communications Style Guide
325+
326+
As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
327+
328+
- **Focus on solutions, not problems**
329+
_Rather than describing the negatives and shortcomings of an existing project, process, or group, focus on highlighting the benefits, outcomes, and positive impacts of the solution. Be constructive and accentuate the positive._
330+
331+
- **Use Plain Language**
332+
_Be clear and concise when explaining concepts. Avoid jargon unless it is necessary and well-defined. Use active voice to be clearer and more engaging._
333+
334+
- **Focus on the audience**
335+
_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
336+
337+
Please refer to the style guides below for additional tips and guidance:
338+
339+
- CMS Resources
340+
- [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
341+
- [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
342+
- [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
343+
344+
- [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
345+
346+
- [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
347+
324348
#### Results
325349
*Insert Review Here*
326350

‎tier3/checklist.pdf

12.9 KB
Binary file not shown.

‎tier3/hooks/post_gen_project.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,6 @@
1111
ADD_MAINTAINER = '{{cookiecutter.add_maintainer}}'
1212

1313
def createGithubRepo():
14-
subprocess.call(["git", "init", "-b", "main"])
15-
subprocess.call(["git", "add", "."])
16-
subprocess.call(["git", "commit", "-m", "first commit"])
1714
gh_cli_command = [
1815
"gh", "repo", "create",
1916
f"{ORG_NAME}/{REPO_NAME}",
@@ -77,6 +74,10 @@ def moveCookiecutterFile():
7774
shutil.move(source_path, destination_path)
7875

7976
def main():
77+
subprocess.call(["git", "init", "-b", "main"])
78+
subprocess.call(["git", "add", "."])
79+
subprocess.call(["git", "commit", "-m", "initial commit"])
80+
8081
if CREATE_REPO == "True":
8182
createGithubRepo()
8283

‎tier4/checklist.md

+24
Original file line numberDiff line numberDiff line change
@@ -322,6 +322,30 @@ The project should include the following files and sections [(link to templates)
322322

323323
*Contains metadata about the project, refer to [Review Project Metadata](#review-project-metadata)*
324324

325+
#### Communications Style Guide
326+
327+
As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
328+
329+
- **Focus on solutions, not problems**
330+
_Rather than describing the negatives and shortcomings of an existing project, process, or group, focus on highlighting the benefits, outcomes, and positive impacts of the solution. Be constructive and accentuate the positive._
331+
332+
- **Use Plain Language**
333+
_Be clear and concise when explaining concepts. Avoid jargon unless it is necessary and well-defined. Use active voice to be clearer and more engaging._
334+
335+
- **Focus on the audience**
336+
_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
337+
338+
Please refer to the style guides below for additional tips and guidance:
339+
340+
- CMS Resources
341+
- [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
342+
- [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
343+
- [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
344+
345+
- [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
346+
347+
- [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
348+
325349
#### Results
326350
*Insert Review Here*
327351

‎tier4/checklist.pdf

14.1 KB
Binary file not shown.

‎tier4/hooks/post_gen_project.py

+4-3
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,6 @@
1111
ADD_MAINTAINER = '{{cookiecutter.add_maintainer}}'
1212

1313
def createGithubRepo():
14-
subprocess.call(["git", "init", "-b", "main"])
15-
subprocess.call(["git", "add", "."])
16-
subprocess.call(["git", "commit", "-m", "first commit"])
1714
gh_cli_command = [
1815
"gh", "repo", "create",
1916
f"{ORG_NAME}/{REPO_NAME}",
@@ -77,6 +74,10 @@ def moveCookiecutterFile():
7774
shutil.move(source_path, destination_path)
7875

7976
def main():
77+
subprocess.call(["git", "init", "-b", "main"])
78+
subprocess.call(["git", "add", "."])
79+
subprocess.call(["git", "commit", "-m", "initial commit"])
80+
8081
if CREATE_REPO == "True":
8182
createGithubRepo()
8283

0 commit comments

Comments
 (0)