Merge branch 'guide-improvements'

docs/guides/documentation/change-log/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">A guide for setting up a log to document software changes in a human-centric format.</pre>
 
+![changelog-screenshot-example](/img/changelog-screen.png)
+
+*Example CHANGELOG.md template rendering*
+
 ## Introduction
 
 **Background**: A change log is a vital tool for documenting significant changes in software over time in a format accessible to humans. It plays a critical role in conveying the evolution of software, including additions, deprecations, and removals. This guide outlines the best practices for maintaining a `CHANGELOG.md` file, complementing release pages and enhancing software distribution transparency.
@@ -21,7 +25,7 @@
 
 ## Quick Start
 
-**[⬇️ Keep a Changelog](https://keepachangelog.com/en/1.0.0/#how)**
+**[⬇️ Keep a Changelog](https://keepachangelog.com/en/1.0.0/#how)** ([see example](https://github.com/riverma/terraformly/blob/main/CHANGELOG.md))
 
 Download a template for creating a human-readable change log for your software project.
 

docs/guides/documentation/documentation-hosts/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">Guidance on selecting and implementing documentation hosting tools.</pre>
 
+![docs-screenshot-example](/img/docs-screen.png)
+
+*Example documentation hosts (no endorsement implied)*
+
 ## Introduction
 
 **Background**: Choosing the right platform for hosting various types of documentation is crucial for project success. This guide explores use cases for different documentation types and recommends tools for hosting user, developer, admin, API docs, and more, aiding in informed decision-making for documentation management.

docs/guides/documentation/readme/index.md

@@ -2,6 +2,10 @@
 
 <pre align="center">A guide to constructing an effective and impressive README for your project.</pre>
 
+![readme-screenshot-example](/img/readme-screen.png)
+
+*Example README.md template rendering*
+
 ## Introduction
 
 **Background**: A well-crafted `README.md` is essential for introducing your software repository. It serves as the first point of contact for developers and users, providing a concise and clear overview. This guide offers a template suitable for various software projects, aiding in the creation of effective README files.
@@ -24,7 +28,7 @@
 
 ## Quick Start
 
-**[⬇️ README Template](README-TEMPLATE)**
+**[⬇️ README Template](README-TEMPLATE)** ([see example](https://github.com/riverma/terraformly/blob/main/README.md))
 
 Download and fill-out our recommended README template to get started on crafting your project's introduction.
 

docs/guides/governance/contributions/code-of-conduct/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">A walkthrough on setting up a code-of-conduct policy for your project.</pre>
 
+![code-of-conduct-screenshot-example](/img/code-of-conduct-screen.png)
+
+*Example CODE_OF_CONDUCT.md template rendering*
+
 ## Introduction
 
 **Background**: A Code of Conduct is important in setting the standards for interaction within a project team. It promotes a positive community environment, addressing unacceptable behaviors and providing mechanisms for conflict resolution. In this guide, we'll help you bootstrap your project with a recommended a Code of Conduct, notably the Contributor Covenant, which is widely recognized and adopted in open-source communities.
@@ -21,7 +25,7 @@
 
 ## Quick Start
 
-**[⬇️ Contributor Covenant Template](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md)**
+**[⬇️ Contributor Covenant Template](https://www.contributor-covenant.org/version/2/1/code_of_conduct/code_of_conduct.md)** ([see example](https://github.com/riverma/terraformly/blob/main/CODE_OF_CONDUCT.md))
 
 Access the standard Contributor Covenant template for a robust Code of Conduct policy to use in your project.
 

docs/guides/governance/contributions/contributing-guide/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">Fast track developing a contribution guide for your new contributors.</pre>
 
+![contributing-screenshot-example](/img/contributing-screen.png)
+
+*Example CONTRIBUTING.md template rendering*
+
 ## Introduction
 
 **Background**: A well-defined contribution guide is crucial for open-source projects. It helps new contributors understand the expectations and processes for contributing effectively. We walk you through developing a contribution guide for your project via our template, which sets clear standards for contributions and details a recommended process to follow.
@@ -22,7 +26,7 @@
 
 ## Quick Start
 
-**[⬇️ Contributing Guide Template](CONTRIBUTING)**
+**[⬇️ Contributing Guide Template](CONTRIBUTING)** ([see example](https://github.com/riverma/terraformly/blob/main/CONTRIBUTING.md))
 
 Download our customizable template to create a contributing guide for your project.
 

docs/guides/governance/contributions/issue-templates/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">Make issue tracking clear and consistent with structured issue templates for your contributors.</pre>
 
+![issue-bug-screenshot-example](/img/issue-bug-screen.png)
+
+*Example bug issue ticket template rendering*
+
 ## Introduction
 
 **Background**: Implementing issue templates in GitHub projects standardizes and clarifies the submission of bug reports, feature requests, and other types of issues. It guides contributors in providing essential details, helping developers understand and address issues more efficiently.
@@ -23,14 +27,16 @@
 ## Quick Start
 
 **Bug Reports:**
-- **[⬇️ Bug Report Template (Markdown)](bug-reports/bug_report)**
-- **[⬇️ Bug Report Template (GitHub Form)](bug-reports/bug_report.yml)**
+- **[⬇️ Bug Report Template (Markdown)](bug-reports/bug_report)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=bug&projects=&template=bug_report.md&title=%5BBug%5D%3A+))
+- **[⬇️ Bug Report Template (GitHub Form)](bug-reports/bug_report.yml)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=bug&projects=&template=bug_report.yml&title=%5BBug%5D%3A+))
 
 **New Features:**
-- **[⬇️ New Feature Template (Markdown)](features/new_feature)**
-- **[⬇️ New Feature Template (GitHub Form)](features/new_feature.yml)**
+- **[⬇️ New Feature Template (Markdown)](features/new_feature)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.md&title=%5BNew+Feature%5D%3A+))
+- **[⬇️ New Feature Template (GitHub Form)](features/new_feature.yml)** ([see example](https://github.com/riverma/terraformly/issues/new?assignees=&labels=enhancement&projects=&template=feature_request.yml&title=%5BNew+Feature%5D%3A+))
+
+**Resources: **
 
-**[📔 GitHub Issue Template Documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates)**
+**[📔 GitHub Issue Template Documentation](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/about-issue-and-pull-request-templates)** 
 
 ---
 

docs/guides/governance/contributions/pull-requests/README.md

@@ -1,6 +1,10 @@
 # Pull Requests
 
-<pre align="center">A walk-through on using our standardized template for pull requests.</pre>
+<pre align="center">A template to standardize pull-requests.</pre>
+
+![pr-screenshot-example](/img/pr-screen.png)
+
+*Example pull request template in action rendering*
 
 ## Introduction
 
@@ -21,7 +25,7 @@
 
 ## Quick Start
 
-**[⬇️ Pull Request Template](PULL_REQUEST_TEMPLATE)**
+**[⬇️ Pull Request Template](PULL_REQUEST_TEMPLATE)** ([see example](https://github.com/riverma/terraformly/blob/main/.github/PULL_REQUEST_TEMPLATE))
 
 Our recommended pull request template for projects.
 

docs/guides/governance/governance-model/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">Establish a project guide for effective open source governance.</pre>
 
+![governance-screenshot-example](/img/governance-screen.png)
+
+*Example GOVERNANCE.md template rendering*
+
 ## Introduction
 
 **Background**: A governance model is essential for government-sponsored open source projects, particularly for medium and large-sized teams. It helps in liberal acceptance of public contributions while retaining decision-making authority with funding sources. This guide provides a template to integrate a generalized governance model into your project, promoting clear operational structure and community engagement.
@@ -22,7 +26,7 @@
 
 ## Quick Start
 
-**[Governance Model Template](GOVERNANCE-TEMPLATE.md)**
+**[Governance Model Template](GOVERNANCE-TEMPLATE.md)** ([see example](https://nasa-ammos.github.io/slim/docs/about/GOVERNANCE/))
 
 Access our recommended template to start integrating a governance model into your project.
 

docs/guides/software-lifecycle/security/github-security/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">Recommendations for enabling GitHub security features for your repositories.</pre>
 
+![gh-security-screenshot-example](/img/gh-security-screen.png)
+
+*Example GitHub security tools rendering*
+
 ## Introduction
 
 **Background:** GitHub offers a suite of security features to help maintainers and developers protect their code and ensure the safety of their repositories. From automatically detecting vulnerabilities in dependencies to scanning for secrets and setting security policies, these tools are essential for any project, especially in today’s security-conscious environment.

docs/guides/software-lifecycle/security/secrets-detection/README.md

@@ -2,6 +2,10 @@
 
 <pre align="center">Guide to identify and automatically prevent leaking of sensitive information into your codebase.</pre>
 
+![secrets-screenshot-example](/img/secrets-screen.png)
+
+*Example secrets scanning rendering*
+
 ## Introduction
 
 **Background**: Sensitive information like API keys, passwords or tokens may be inadvertently committed to your repository. Such slip-ups can pose significant security risks. We recommend not only recurring scans for sensitive information, but proactively preventing sensitive information from getting infused. To support these goals, we recommend a tool called [detect-secrets](https://github.com/Yelp/detect-secrets) that mitigates these risks. It scans for common sensitive information categories like passwords and other high-entropy values that contain sensitive data. It also provides a plugin system to support additional customization. It's fast for use in continuous integration pipelines and quickly executes on local-developer machines. It uses a "baseline file" approach, leveraging `.secrets.baseline`, that streamlines management of legitimate secrets and reduces false positives. This helps both new and established projects detect and prevent secrets from entering the code base.
@@ -59,23 +63,6 @@ Additional steps like whitelisting accepted values and false positives, establis
 
 There are three recommended layers of protection we suggest you enable to ensure comprehensive security. Please see below sections for further details. 
 
-### Table of Contents
-- [Secrets Detection](#secrets-detection)
-  - [Introduction](#introduction)
-  - [Prerequisites](#prerequisites)
-  - [Quick Start](#quick-start)
-  - [Step-by-Step Guide](#step-by-step-guide)
-    - [Table of Contents](#table-of-contents)
-    - [Layer 1: Full Scan and Audit (Client-side)](#layer-1-full-scan-and-audit-client-side)
-      - [Steps](#steps)
-    - [Layer 2: Git Commit Scan (Client-side)](#layer-2-git-commit-scan-client-side)
-      - [Steps](#steps-1)
-    - [Layer 3: Server-side Push to GitHub.com](#layer-3-server-side-push-to-githubcom)
-      - [Steps](#steps-2)
-    - [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq)
-  - [Credits](#credits)
-  - [Feedback and Contributions](#feedback-and-contributions)
-
 ### Layer 1: Full Scan and Audit (Client-side)
 This layer directly scans the developer's local environment using the `detect-secrets` tool. After scanning, a baseline file containing detected secrets is generated. Developers can audit this file for detailed information on detected secrets.