Outbound Checklists: Added Communications Style Guide

.github/workflows/checklistMarkdownToPDF.yml

@@ -4,7 +4,7 @@ on:
         types: [opened, synchronize]
     # Paths can be used to only trigger actions when you have edited checklist files
         branches:
-        - 'checklists/**'
+        - 'dev'
         paths:
         - 'tier*/checklist.md'
 

README.md

@@ -45,6 +45,15 @@ this question - `"project_name": "My Project",`.  See the [cookiecutter docs](ht
 for more information.
 
 ## Repolinter
+
+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!
+
+✔    =  Pass
+
+✖    =  Fail
+
+⚠  =  Warn
+
 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.
 
 Sample commands to run with the given repolinter.json path:

tier0/hooks/post_gen_project.py

@@ -8,9 +8,6 @@
 RECEIVE_UPDATES = '{{cookiecutter.receive_updates}}'
 
 def createGithubRepo():
-    subprocess.call(["git", "init", "-b", "main"])
-    subprocess.call(["git", "add", "."])
-    subprocess.call(["git", "commit", "-m", "first commit"])
     gh_cli_command = [
         "gh", "repo", "create",
         f"{ORG_NAME}/{REPO_NAME}",
@@ -30,6 +27,10 @@ def addTopic():
     ]
     subprocess.call(gh_cli_command)
 
+subprocess.call(["git", "init", "-b", "main"])
+subprocess.call(["git", "add", "."])
+subprocess.call(["git", "commit", "-m", "initial commit"])
+
 if CREATE_REPO == "True":
     createGithubRepo()
 

tier1/checklist.md

@@ -192,7 +192,7 @@ repolinter lint .
 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
 
 
- **Review Content**
+ #### Review Content
 
  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):
 
@@ -237,6 +237,30 @@ repolinter lint .
 
     *Contains metadata about the project, refer to [Review Project Metadata](#review-project-metadata)*
 
+#### Communications Style Guide
+
+As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
+
+-   **Focus on solutions, not problems**
+_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._
+
+-   **Use Plain Language**
+_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._
+
+-   **Focus on the audience**
+_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
+
+Please refer to the style guides below for additional tips and guidance:
+
+-   CMS Resources
+    -   [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
+    -   [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
+    -   [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
+
+-   [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
+
+-   [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
+
 #### Results
 *Insert Review Here*
 

tier1/hooks/post_gen_project.py

@@ -10,9 +10,6 @@
 RECEIVE_UPDATES = '{{cookiecutter.receive_updates}}'
 
 def createGithubRepo():
-    subprocess.call(["git", "init", "-b", "main"])
-    subprocess.call(["git", "add", "."])
-    subprocess.call(["git", "commit", "-m", "first commit"])
     gh_cli_command = [
         "gh", "repo", "create",
         f"{ORG_NAME}/{REPO_NAME}",
@@ -43,6 +40,10 @@ def moveCookiecutterFile():
     shutil.move(source_path, destination_path)
 
 def main():
+    subprocess.call(["git", "init", "-b", "main"])
+    subprocess.call(["git", "add", "."])
+    subprocess.call(["git", "commit", "-m", "initial commit"])
+
     if CREATE_REPO == "True":
         createGithubRepo()
 

tier2/checklist.md

@@ -281,6 +281,30 @@ The project should include the following files and sections [(link to templates)
 
     *Lists project maintainers and their responsibilities*
 
+#### Communications Style Guide
+
+As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
+
+-   **Focus on solutions, not problems**
+_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._
+
+-   **Use Plain Language**
+_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._
+
+-   **Focus on the audience**
+_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
+
+Please refer to the style guides below for additional tips and guidance:
+
+-   CMS Resources
+    -   [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
+    -   [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
+    -   [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
+
+-   [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
+
+-   [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
+
 
 #### Results
 *Insert Review Here*

tier2/hooks/post_gen_project.py

@@ -11,9 +11,6 @@
 ADD_MAINTAINER = '{{cookiecutter.add_maintainer}}'
 
 def createGithubRepo():
-    subprocess.call(["git", "init", "-b", "main"])
-    subprocess.call(["git", "add", "."])
-    subprocess.call(["git", "commit", "-m", "first commit"])
     gh_cli_command = [
         "gh", "repo", "create",
         f"{ORG_NAME}/{REPO_NAME}",
@@ -84,6 +81,10 @@ def moveCookiecutterFile():
     shutil.move(source_path, destination_path)
 
 def main():
+    subprocess.call(["git", "init", "-b", "main"])
+    subprocess.call(["git", "add", "."])
+    subprocess.call(["git", "commit", "-m", "initial commit"])
+
     if CREATE_REPO == "True":
         createGithubRepo()
 

tier3/checklist.md

@@ -321,6 +321,30 @@ The project should include the following files and sections [(link to templates)
 
     *Contains metadata about the project, refer to [Review Project Metadata](#review-project-metadata)*
 
+#### Communications Style Guide
+
+As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
+
+-   **Focus on solutions, not problems**
+_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._
+
+-   **Use Plain Language**
+_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._
+
+-   **Focus on the audience**
+_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
+
+Please refer to the style guides below for additional tips and guidance:
+
+-   CMS Resources
+    -   [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
+    -   [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
+    -   [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
+
+-   [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
+
+-   [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
+
 #### Results
 *Insert Review Here*
 

tier3/hooks/post_gen_project.py

@@ -11,9 +11,6 @@
 ADD_MAINTAINER = '{{cookiecutter.add_maintainer}}'
 
 def createGithubRepo():
-    subprocess.call(["git", "init", "-b", "main"])
-    subprocess.call(["git", "add", "."])
-    subprocess.call(["git", "commit", "-m", "first commit"])
     gh_cli_command = [
         "gh", "repo", "create",
         f"{ORG_NAME}/{REPO_NAME}",
@@ -77,6 +74,10 @@ def moveCookiecutterFile():
     shutil.move(source_path, destination_path)
 
 def main():
+    subprocess.call(["git", "init", "-b", "main"])
+    subprocess.call(["git", "add", "."])
+    subprocess.call(["git", "commit", "-m", "initial commit"])
+
     if CREATE_REPO == "True":
         createGithubRepo()
 

tier4/checklist.md

@@ -322,6 +322,30 @@ The project should include the following files and sections [(link to templates)
 
     *Contains metadata about the project, refer to [Review Project Metadata](#review-project-metadata)*
 
+#### Communications Style Guide
+
+As you are writing content about the repository, consider the following when describing the project, the agency, and how work is done:
+
+-   **Focus on solutions, not problems**
+_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._
+
+-   **Use Plain Language**
+_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._
+
+-   **Focus on the audience**
+_Write for a broad audience, ensuring that developers, stakeholders, end-users, and viewers of all skill levels can understand and engage with the content._
+
+Please refer to the style guides below for additional tips and guidance:
+
+-   CMS Resources
+    -   [Guidelines for Effective Writing](https://www.cms.gov/training-education/learn/find-tools-to-help-you-help-others/guidelines-for-effective-writing)
+    -   [Tone of Voice section in Branding Guide](https://www.cms.gov/About-CMS/Agency-Information/CMS-Brand-Identity/Downloads/Branding-Guide.pdf)
+    -   [2020 Plain Writing Report](https://www.medicare.gov/media/2020-Annual-Plain-Writing-Report.pdf)
+
+-   [18F Style Guide](https://guides.18f.gov/content-guide/our-style/) 
+
+-   [UK Content Style Guide](https://design.homeoffice.gov.uk/content-style-guide/designing-for-limited-english)
+
 #### Results
 *Insert Review Here*
 

tier4/hooks/post_gen_project.py

@@ -11,9 +11,6 @@
 ADD_MAINTAINER = '{{cookiecutter.add_maintainer}}'
 
 def createGithubRepo():
-    subprocess.call(["git", "init", "-b", "main"])
-    subprocess.call(["git", "add", "."])
-    subprocess.call(["git", "commit", "-m", "first commit"])
     gh_cli_command = [
         "gh", "repo", "create",
         f"{ORG_NAME}/{REPO_NAME}",
@@ -77,6 +74,10 @@ def moveCookiecutterFile():
     shutil.move(source_path, destination_path)
 
 def main():
+    subprocess.call(["git", "init", "-b", "main"])
+    subprocess.call(["git", "add", "."])
+    subprocess.call(["git", "commit", "-m", "initial commit"])
+
     if CREATE_REPO == "True":
         createGithubRepo()