docs: apply Snyk writing-style skill to Discover Snyk pages by TashaTBaker · Pull Request #1367 · snyk/user-docs

TashaTBaker · 2026-06-18T10:12:27Z

Applies the Snyk documentation writing-style rules across the Discover Snyk section (95 files).

Part of the per-section writing-style review. Targets the shared base branch writing-style-review.

Consistent changes

Passive to active voice, naming the actor; present tense over future "will"
Capability phrasing: "allows/enables you to" to "lets you" / "you can"
Word choice: via to through/using; in order to to "to"; prior to to before; once to after; e.g./i.e./etc. to for example/that is/and so on; & to and
Removed brand possessives, AI buzzwords, and filler (just, simply, easily)
Sentence-case headings; bold UI labels; Projects/Organizations/Groups casing
Fixed copy-paste provider errors (for example GitHub vs GitLab) and obvious prose typos

Preserved

Frontmatter, GitBook components, HTML tables, links/URLs, image paths, and technical literals are unchanged. SUMMARY.md (navigation) not touched.

Generated with Claude Code

Apply the Snyk documentation writing-style rules across the discover-snyk section (95 files updated). Consistent changes: - Passive to active voice, naming the actor; present tense over future "will" - Capability phrasing ("allows/enables you to" -> "lets you"/"you can") - Word choice: via -> through/using; in order to -> to; prior to -> before; once -> after; e.g./i.e./etc. -> for example/that is/and so on; & -> and - Remove brand possessives, AI buzzwords, and filler (just, simply, easily) - Sentence-case headings; bold UI labels; Projects/Organizations/Groups casing - Fix copy-paste provider errors and obvious prose typos Frontmatter, GitBook components, HTML tables, links, and technical literals unchanged. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

snyk-io · 2026-06-18T10:12:54Z

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

TashaTBaker · 2026-06-18T11:22:12Z

 ## Generate a GitLab PAT

-Generate a GitHub PAT with the following permissions enabled:\\
+Generate a GitLab PAT with the following permissions enabled:\\


@mikeromard Looking at this the instructions in the Pilot guide are confusing. This is from Group GitLab, but it is asking you to create a GitHub PAT and then select the GitHub integration tile when there is a GitLab one. I can see you and Ann worked on this from the page history, so wondering if you can clarify?

I didn't author this, but I expect this is just a copy/paste error, and it should say GitLab PAT.

Visit replacing see

TashaTBaker · 2026-06-18T11:27:56Z

 <figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcmljy-ooiInsutXG8MAz5nwwTDGFlODl6YGUnbdx942g-RUiuVDMExkkAXG0cCPkcbsh6uT-eJdURlItkQSUZfxGHbYUhLlxqNMI0IFDIX2paJE45ywN6kX3zB2SMlZ_rg4cqb?key=i_CNrr-DvB8PGUAzq09BT3pc" alt=""><figcaption></figcaption></figure>

-Click on the 'Not tested' section of the first pie chart on the overview page, or use coverage filters on the 'All Assets' page to view all repositories that the selected Snyk product has not tested.
+Click the 'Not tested' section of the first pie chart on the overview page, or use coverage filters on the 'All Assets' page to view all repositories that the selected Snyk product has not tested.


I believe this is a UI element so should be bold.

web is not capitalised

TashaTBaker · 2026-06-18T11:34:28Z

 There are a number of different features available that can be used to help you gradually introduce the feature to avoid friction with your development teams:

-* Fail conditions: You can control whether the test will "fail" if the PR itself is adding a dependency with issues (most common) or if the repository as a whole has any issues.
+* Fail conditions: You can control whether the test "fails" if the PR itself is adding a dependency with issues (most common) or if the repository as a whole has any issues.


Not sure why "" is used here. If this is in the UI it should be bold.

and if it's not in the UI, the " should be dropped (here and elsewhere).

TashaTBaker · 2026-06-18T11:34:55Z

 ## Common prevention methods

-Below are the two common areas that allow you to "prevent new issues":&#x20;
+The two common areas that let you "prevent new issues" are:&#x20;


Why use the "" ? Unsure why this is here, hunch is to remove.

TashaTBaker · 2026-06-18T13:22:43Z

-   1. Install the dependencies into the packages folder by running `nuget install -OutputDirectory packages`
-   2. Ensure that the packages directory has been created by the previous command.
-   3. Run `snyk test`.
+3. Run `snyk test`.


@aluca3 It seems to have removed some sub-steps. Can you confirm that we need to keep these sub-steps?

TashaTBaker · 2026-06-18T13:24:29Z

 ### Directory layout

-Snyk Code relies on Python projects to follow a standard directory layout for accurate analysis. Specifically, Snyk Code expects Projects to be compatible with [`setuptools` automatic discovery](https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#auto-discovery), which identifies packages and modules automatically based on the directory structure. This includes support for `init.py` files to ensure that symbols defined in package initialization files are imported correctly, leading to a more accurate and deeper analysis.
+Snyk Code relies on Python Projects to follow a standard directory layout for accurate analysis. Specifically, Snyk Code expects Projects to be compatible with [`setuptools` automatic discovery](https://setuptools.pypa.io/en/latest/userguide/package_discovery.html#auto-discovery), which identifies packages and modules automatically based on the directory structure. This includes support for `init.py` files to ensure that symbols defined in package initialization files are imported correctly, leading to a more accurate and deeper analysis.


I think this should be lowercase projects

mikeromard · 2026-06-18T12:56:02Z

 {% include "../../../../.gitbook/includes/pilot-guide-navigation.md" %}

-‌Review the steps below to configure the Bitbucket integration with Snyk. For more details about setting up the GitHub integration, contact your Snyk account team.\\
+‌Review the following steps to configure the Bitbucket integration with Snyk. For more details about setting up the integration, contact your Snyk account team.\\


Suggested change

‌Review the following steps to configure the Bitbucket integration with Snyk. For more details about setting up the integration, contact your Snyk account team.\\

‌Review the following steps to configure the Bitbucket integration with Snyk. For more details about setting up the integration, contact your Snyk account team.

mikeromard · 2026-06-18T13:03:12Z

 ## Generate a GitLab PAT

-Generate a GitHub PAT with the following permissions enabled:\\
+Generate a GitLab PAT with the following permissions enabled:\\


I didn't author this, but I expect this is just a copy/paste error, and it should say GitLab PAT.

mikeromard · 2026-06-18T13:15:45Z

 <figure><img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcmljy-ooiInsutXG8MAz5nwwTDGFlODl6YGUnbdx942g-RUiuVDMExkkAXG0cCPkcbsh6uT-eJdURlItkQSUZfxGHbYUhLlxqNMI0IFDIX2paJE45ywN6kX3zB2SMlZ_rg4cqb?key=i_CNrr-DvB8PGUAzq09BT3pc" alt=""><figcaption></figcaption></figure>

-Click on the 'Not tested' section of the first pie chart on the overview page, or use coverage filters on the 'All Assets' page to view all repositories that the selected Snyk product has not tested.
+Click the 'Not tested' section of the first pie chart on the overview page, or use coverage filters on the 'All Assets' page to view all repositories that the selected Snyk product has not tested.


mikeromard · 2026-06-18T13:16:23Z

-The Class column is available for each repository. This class is meant to reflect the business criticality of the asset from A (most critical) to D (least critical). Try setting a few of your most important repos manually to Class A. This attribute can be used in reporting to help focus on issues from your company’s most important repositories.
+The Class column is available for each repository. This class reflects the business criticality of the asset from A (most critical) to D (least critical). Try setting a few of your most important repos manually to Class A. You can use this attribute in reporting to help focus on issues from your company’s most important repositories.

 \\


This line should be removed

mikeromard · 2026-06-18T13:17:24Z

-An assessment of whether applicable assets are scanned and tested by security tools (like Snyk Open Source, for instance), as it relates to an application security program. A type of policy that allows you to specify what controls should be applied and, optionally, how often it needs to be run.
+An assessment of whether applicable assets are scanned and tested by security tools (like Snyk Open Source, for instance), as it relates to an application security program. A type of policy that lets you specify what controls to apply and, optionally, how often it needs to be run.

 ### Coverage gap (Snyk **Essentials**)


Suggested change

### Coverage gap (Snyk **Essentials**)

### Coverage gap (Snyk Essentials)

Can we update the writing-style skill to remove bold from headers?

mikeromard · 2026-06-18T13:33:23Z

 * Using the [Snyk CLI](https://app.gitbook.com/o/-M4tdxG8qotLgGZnLpFR/s/IEEjSXQQu36y0vmFV8zf/snyk-cli/snyk-cli) and running the specific commands directly.

-Each option has benefits - using an existing pipeline integration may be faster and easier to configure, but using the Snyk CLI will give you a greater range of options and flexibility in your "fail" criteria.
+Each option has benefits — using an existing pipeline integration may be faster to configure, but using the Snyk CLI gives you a greater range of options and flexibility in your "fail" criteria.


Suggested change

Each option has benefits — using an existing pipeline integration may be faster to configure, but using the Snyk CLI gives you a greater range of options and flexibility in your "fail" criteria.

Each option has benefits. Using an existing pipeline integration may be faster to configure, but using the Snyk CLI gives you a greater range of options and flexibility in your fail criteria.

mikeromard · 2026-06-18T13:34:00Z

 There are a number of different features available that can be used to help you gradually introduce the feature to avoid friction with your development teams:

-* Fail conditions: You can control whether the test will "fail" if the PR itself is adding a dependency with issues (most common) or if the repository as a whole has any issues.
+* Fail conditions: You can control whether the test "fails" if the PR itself is adding a dependency with issues (most common) or if the repository as a whole has any issues.


and if it's not in the UI, the " should be dropped (here and elsewhere).

mikeromard · 2026-06-18T13:41:44Z

 3. Submit to your certification body.
   1. Access the CPE submission portal of your certifying organization, such as ISC2 or ISACA.
-   2. Enter the recorded details and provide any required documentation, such as completion certificates (available for Learning Paths) or screenshots of the completed lesson in your Learning Progress dashboard or the lesson page, see examples below.
+   2. Enter the recorded details and provide any required documentation, such as completion certificates (available for Learning Paths) or screenshots of the completed lesson in your Learning Progress dashboard or the lesson page. See the following examples.


I don't think we can say "See the following examples" unless the examples follow immediately. In this case, there's another step before the examples. We could maybe drop "following" and link to the examples section

mikeromard · 2026-06-18T13:42:29Z

-The platform provides an easy way for teams to get an introduction to Snyk tools and user best practices. Most courses take between three and ten minutes.
+The platform provides a way for teams to get an introduction to Snyk tools and user best practices. Most courses take between three and 10 minutes.

 Snyk offers product training[ learning paths](https://learn.snyk.io/catalog/?type=product-training\&format=learning_path), including Implementing Snyk, Managing application security with Snyk, and Developing using Snyk.


Suggested change

Snyk offers product training[ learning paths](https://learn.snyk.io/catalog/?type=product-training\&format=learning_path), including Implementing Snyk, Managing application security with Snyk, and Developing using Snyk.

Snyk offers product training [learning paths](https://learn.snyk.io/catalog/?type=product-training\&format=learning_path), including Implementing Snyk, Managing application security with Snyk, and Developing using Snyk.

mikeromard · 2026-06-18T13:46:19Z

 * To scan a specific project (for example, myapp), use `--sub-project=` (that is, `snyk test --sub-project=myapp`).

-specific configurations, [Snyk for Java and Kotlin](../../../supported-languages-package-managers-and-frameworks/java-and-kotlin/).
+For specific configurations, see [Snyk for Java and Kotlin](../../../supported-languages-package-managers-and-frameworks/java-and-kotlin/).


Shouldn't this be visit, rather than see?

TashaTBaker requested a review from a team as a code owner June 18, 2026 10:12

TashaTBaker mentioned this pull request Jun 18, 2026

docs: writing-style review — all sections (integration) #1371

Draft