From 4341af88fc5419d63922c5124724102691a56944 Mon Sep 17 00:00:00 2001 From: Felix Sargent Date: Thu, 19 Feb 2026 17:42:52 +0000 Subject: [PATCH] Added writing style guide and Snyk rules to improve documentation standards; updated .gitignore to include auto-generated rules file. --- .cursor/rules/gitbook_skill.md | 945 +++++++++++++++++++++ .cursor/rules/writing-rules-style-guide.md | 484 +++++++++++ .cursor/rules/writing-style-guide.mdc | 509 +++++++++++ .gitignore | 3 + 4 files changed, 1941 insertions(+) create mode 100644 .cursor/rules/gitbook_skill.md create mode 100644 .cursor/rules/writing-rules-style-guide.md create mode 100644 .cursor/rules/writing-style-guide.mdc diff --git a/.cursor/rules/gitbook_skill.md b/.cursor/rules/gitbook_skill.md new file mode 100644 index 000000000000..2b2cc1468078 --- /dev/null +++ b/.cursor/rules/gitbook_skill.md @@ -0,0 +1,945 @@ +# skill + +A comprehensive guide for editing GitBook documentation in external environments like Cursor, Claude Code, or other text editors. This skill provides all the formatting syntax, configuration options, and best practices needed to create and maintain GitBook content outside the GitBook web interface. + +### When to Use This Skill + +Use this skill when working with GitBook documentation through: + +* Git-synced repositories (GitHub, GitLab) +* Local markdown editors +* IDE integrations +* Command-line tools +* Any environment where you're editing GitBook content as files rather than through the GitBook UI + +### Quick Reference + +#### GitBook Content Structure + +GitBook organizes content through pages, spaces, and collections: + +* **Pages** are individual markdown files that make up your documentation +* **Spaces** are collections of pages organized into a documentation site +* **Collections** are groups of spaces + +**File structure:** + +``` +/ + .gitbook/ + assets/ # GitBook-managed images and files + includes/ # Reusable content blocks + vars.yaml # Space-level variables + .gitbook.yaml # Configuration + README.md # Homepage + SUMMARY.md # Table of contents + getting-started/ # Section folder + installation.md + quickstart.md + api-reference/ + authentication.md + endpoints.md +``` + +**Frontmatter fields:** + +```markdown +--- +description: Page description for SEO +icon: book-open +hidden: true +vars: + page_variable: value +if: visitor.claims.unsigned.condition +layout: + width: default # or 'wide' + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true + metadata: + visible: true +--- +``` + +**Variables and expressions:** + +* Space variables: `/.gitbook/vars.yaml` +* Page variables: Frontmatter `vars:` +* Expression syntax: `space.vars.variableName` + +**Most common custom blocks:** + +* `{% tabs %}...{% endtabs %}` for alternatives +* `{% hint style="..." %}...{% endhint %}` for callouts +* `{% stepper %}...{% endstepper %}` for sequential steps +* `
......
` for expandable content + +**Links:** + +* External: `[text](https://example.com)` +* Internal: Use relative paths like `[text](page.md)` or `[text](../folder/page.md)` + +**Key reminders:** + +* Read SUMMARY.md first when working with existing content to understand structure +* Test in GitBook after editing locally +* Keep SUMMARY.md synchronized with your file structure +* Variables are defined in `.gitbook/vars.yaml` (space-level) or page frontmatter (page-level) +* OpenAPI specs must be uploaded via API/CLI/UI, not embedded in markdown + +### When to Use Which Block + +Choose the right GitBook block for your content needs: + +| Need | Use | Why | +| ------------------------------------------ | --------------------------- | --------------------------------------------------------------------- | +| Sequential, ordered instructions | `{% stepper %}` | Guides users through multi-step processes with clear progression | +| Alternative options (languages, platforms) | `{% tabs %}` | Lets users choose their relevant option without cluttering the page | +| Optional or detailed information | `
` (Expandable) | Keeps page scannable while providing depth for interested readers | +| Important warnings or tips | `{% hint %}` | Draws attention with colored styling (info, warning, danger, success) | +| Side-by-side comparisons | `{% columns %}` | Shows related information in parallel (max 2 columns) | +| Timeline or changelog | `{% updates %}` | Displays dated entries in reverse chronological order | +| Visual navigation cards | `` | Creates clickable card grid for section navigation | +| Downloadable files | `{% file %}` | Provides files with captions and descriptions | +| Call-to-action links | `` | Highlights primary or secondary actions | +| Reusable content across pages | `{% include %}` | Maintains consistency for repeated content blocks | +| Dynamic content | `` | Displays variable values that update automatically | + +**Variable scope decision:** + +| If variable is... | Define it as... | Access with... | +| -------------------------- | ------------------------------------ | ------------------------- | +| Used across multiple pages | Space-level in `/.gitbook/vars.yaml` | `space.vars.variableName` | +| Specific to one page | Page-level in frontmatter `vars:` | `page.vars.variableName` | + +### Working with Existing Content + +When working with an existing GitBook space that's synced to Git, follow this workflow to understand the structure: + +1. **Read SUMMARY.md first** - This file contains the complete table of contents and navigation structure. It shows you: + * All pages and their hierarchy + * Page groups and organization + * The relative paths to each markdown file +2. **If SUMMARY.md doesn't exist** - GitBook has inferred the structure from your directory layout. Browse the directory structure to understand how pages are organized. +3. **Check .gitbook.yaml** - Review this file to understand: + * Where the root documentation directory is located + * Any custom paths for README.md or SUMMARY.md + * Existing redirects +4. **Explore .gitbook/assets/** - Contains all uploaded images and files referenced in the documentation +5. **Check .gitbook/vars.yaml** - Contains space-level variables if any are defined + +This approach ensures you understand the existing structure before making changes, helping you maintain consistency and avoid breaking internal links. + +### Configuration Files + +#### .gitbook.yaml + +The `.gitbook.yaml` file configures your GitBook space. It should be placed at the root of your documentation directory (or in a subdirectory if using monorepos). + +**Basic structure:** + +```yaml +root: ./ + +structure: + readme: ./README.md + summary: ./SUMMARY.md + +redirects: + old-page: new-page.md + help: support.md +``` + +**Configuration options:** + +* `root`: The root directory for your documentation (default: `./`) +* `structure.readme`: Path to your homepage (default: `./README.md`) +* `structure.summary`: Path to your table of contents (default: `./SUMMARY.md`) +* `redirects`: Key-value pairs mapping old URLs to new page paths + +**Monorepo support:** + +For repositories with multiple documentation projects: + +``` +/ + packages/ + docs/ + .gitbook.yaml + README.md + SUMMARY.md + api/ + .gitbook.yaml + README.md + SUMMARY.md +``` + +When setting up Git Sync, configure the "Project directory" to point to the subdirectory containing the `.gitbook.yaml` file. + +**Important notes:** + +* Paths in `.gitbook.yaml` are relative to the `root` option +* Redirects defined here are space-specific (apply only to this space) +* For site-wide redirects across multiple spaces, use the GitBook UI instead +* When using Git Sync, manage the README file only through your repository to avoid conflicts + +### The .gitbook Directory + +When using Git Sync, GitBook creates a `.gitbook` directory in your repository to store assets, variables, and generated content. + +**Directory structure:** + +``` +.gitbook/ + assets/ # Uploaded images and files + includes/ # Reusable content blocks (exported as individual .md files) + vars.yaml # Space-level variables +``` + +**Important notes about .gitbook:** + +* **Assets**: Images and files uploaded through the GitBook UI are stored in `.gitbook/assets/` +* **Reusable content**: Each reusable content block is exported as a separate markdown file in `.gitbook/includes/` +* **Variables**: Space-level variables are stored in `.gitbook/vars.yaml` as key-value pairs +* **References**: Pages reference reusable content using `{% include "/reusable-content/rc12345" %}` +* **Images**: Markdown pages reference images like `![alt](../.gitbook/assets/image-name.svg)` +* **Table of contents**: The `.gitbook/includes` folder and its files may appear in your space's table of contents. You may need to manually hide them from the TOC if this happens. +* **Location**: In monorepos, the `.gitbook` directory is created in the root of each synced space (not necessarily the repository root) + +#### SUMMARY.md + +The `SUMMARY.md` file defines your table of contents and navigation structure. It's a markdown file with a specific format that mirrors the sidebar navigation in GitBook. + +**Basic structure:** + +```markdown +# Summary + +## Use headings to create page groups like this one + +* [First page's title](page1/README.md) + * [Some child page](page1/page1-1.md) + * [Some other child page](page1/page1-2.md) +* [Second page's title](page2/README.md) + * [Some child page](page2/page2-1.md) + * [Some other child page](page2/page2-2.md) + +## A second page group + +* [Another page](another-page.md) +``` + +**Key rules:** + +* Use `#` for the main title (commonly "Table of contents" or "Summary") +* Use `##` headings to create page groups (section headers in the sidebar) +* Use `*` for unordered lists to define pages and subpages +* Indent with spaces (not tabs) to create nested/child pages +* Each list item should be a markdown link: `[Link text](path/to/file.md)` +* Paths are relative to the location specified in `.gitbook.yaml` (typically the root) + +**Page link titles (optional):** + +You can define a different title for the sidebar navigation versus the page itself: + +```markdown +# Summary + +* [Page main title](page.md "Page link title") +``` + +The text in quotes ("Page link title") will be used in: + +* The table of contents sidebar +* Pagination buttons at the bottom of pages +* Any relative links to that page + +**Important notes:** + +* SUMMARY.md is optional. If not provided, GitBook infers structure from your folder hierarchy +* You cannot reference the same markdown file twice in SUMMARY.md (each page has only one URL) +* GitBook updates SUMMARY.md automatically when you edit through the GitBook UI +* The file structure reflects exactly what users see in the navigation sidebar + +### Markdown Formatting + +GitBook uses GitHub Flavored Markdown with custom extensions. + +**Standard markdown:** + +```markdown +# Heading 1 +## Heading 2 +### Heading 3 + +**bold text** +*italic text* +`inline code` + +- Bullet list item +- Another item + - Nested item + +1. Numbered list +2. Second item + +[Link text](https://example.com) +[Internal link](getting-started.md) +``` + +**Code blocks:** + +````markdown +```javascript +const foo = 'bar'; +console.log(foo); +``` +```` + +**Code blocks with titles:** + +````markdown +{% code title="index.js" %} +```javascript +const foo = 'bar'; +console.log(foo); +``` +{% endcode %} +```` + +**Inline links:** + +* External links: `[text](https://example.com)` +* Internal pages: Use relative file paths like `[text](page.md)`, `[text](../folder/page.md)`, or `[text](subfolder/page.md)` +* Email: `[text](mailto:email@example.com)` + +**Math/TeX:** + +```markdown +Inline formula: $$E = mc^2$$ + +Block formula: + +$$ +E = mc^2 +$$ +``` + +### Page Frontmatter + +GitBook supports YAML frontmatter at the top of markdown files to configure page-specific settings. Frontmatter must be placed at the very beginning of the file, before any content. + +**Available frontmatter fields:** + +```markdown +--- +description: Page description used for SEO and page previews +icon: book-open +hidden: true +vars: + page_variable: value + another_var: another value +if: visitor.claims.unsigned.isPremium +layout: + width: default + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true + metadata: + visible: true +--- +``` + +**Field descriptions:** + +* **`description:`** - Page description text. Supports multiline with `>-` syntax: + + ```yaml + description: >- + This is a longer description + that spans multiple lines + ``` +* **`icon:`** - Icon name from Font Awesome (e.g., `book-open`, `bolt`, `stars`, `icons`, `brackets-curly`) +* **`hidden: true`** - Hides the page from the table of contents in published documentation +* **`vars:`** - Page-level variables (key-value pairs) that can be referenced in expressions: + + ```yaml + vars: + version: v1.2.3 + api_key: example_key + ``` +* **`if:`** - Adaptive content visibility condition. Controls when the page is visible based on visitor attributes: + + ```yaml + if: visitor.claims.unsigned.isPremium + ``` + + **Note:** While adaptive content conditions can be set in frontmatter, it's recommended to configure them through the GitBook UI for better maintainability and team visibility. +* **`layout:`** - Controls page layout and which elements are visible. This maps to the "Page Options" settings in the GitBook UI: + + * **`width:`** - Page content width + * `default` - Standard content width + * `wide` - Wider content area (automatically widens full-width blocks like tables and code) + * **`title.visible:`** - Show/hide the page title (boolean: `true` or `false`) + * **`description.visible:`** - Show/hide the page description (boolean: `true` or `false`) + * **`tableOfContents.visible:`** - Show/hide the left sidebar table of contents (boolean: `true` or `false`) + * **`outline.visible:`** - Show/hide the right sidebar page outline/headings (boolean: `true` or `false`) + * **`pagination.visible:`** - Show/hide next/previous page navigation links (boolean: `true` or `false`) + * **`metadata.visible:`** - Show/hide page metadata section (boolean: `true` or `false`) + + Example for a landing page with minimal chrome: + + ```yaml + layout: + width: wide + title: + visible: true + description: + visible: true + tableOfContents: + visible: false + outline: + visible: false + pagination: + visible: false + ``` + +**Example complete frontmatter:** + +```markdown +--- +description: Create reusable variables that can be referenced in pages and spaces +icon: icons +vars: + latest_version: v3.0.4 + support_email: help@example.com +layout: + width: wide + title: + visible: true + description: + visible: true + tableOfContents: + visible: true + outline: + visible: true + pagination: + visible: true +--- + +# Your Page Title + +Page content starts here... +``` + +### Variables and Expressions + +GitBook supports variables that can be dynamically displayed in your content using expressions. Variables can be defined at the space level or page level. + +#### Variable Storage + +**Space-level variables** are stored in `/.gitbook/vars.yaml` at the root of your documentation: + +```yaml +# .gitbook/vars.yaml +food: apple +latest_version: v3.0.4 +company_name: Acme Corp +``` + +**Page-level variables** are stored in the page's frontmatter under `vars:`: + +```markdown +--- +vars: + page_food: orange + page_version: v2.1.0 +--- +``` + +#### Using Variables with Expressions + +Expressions allow you to reference and display variable values dynamically in your content. Expressions use JavaScript syntax and are wrapped in `` tags. + +**Syntax:** + +```markdown +JavaScript expression here +``` + +**Examples:** + +```markdown + +1 + 1 + + +space.vars.latest_version + + +"My favorite food is " + space.vars.food + + +page.vars.page_food + + +space.vars.latest_version === "v3.0.4" ? "Latest" : "Outdated" +``` + +**Variable references:** + +* `space.vars.variableName` - Access space-level variables defined in `/.gitbook/vars.yaml` +* `page.vars.variableName` - Access page-level variables defined in the page's frontmatter + +**Important notes:** + +* Variable definitions (the actual variable storage) are managed through: + * `/.gitbook/vars.yaml` for space-level variables + * Page frontmatter `vars:` for page-level variables +* Expressions can contain any valid JavaScript code and are evaluated when the page is rendered +* When editing locally, you can create space variables by editing `/.gitbook/vars.yaml` and page variables by adding them to frontmatter +* The GitBook UI provides a visual editor for managing variables, but they are fully editable in markdown files + +### GitBook Custom Blocks + +GitBook extends standard markdown with custom block syntax using tags like `{% tabs %}`, `{% hint %}`, etc. These blocks enable rich, interactive documentation features. + +#### Tabs + +Use tabs to present alternative content like different programming languages or platform-specific instructions. + +**When to use:** Comparing alternatives (code in different languages, platform-specific commands, configuration options). + +**Syntax:** + +````markdown +{% tabs %} +{% tab title="JavaScript" %} +```javascript +const greeting = 'Hello World'; +console.log(greeting); +``` +{% endtab %} + +{% tab title="Python" %} +```python +greeting = "Hello World" +print(greeting) +``` +{% endtab %} +{% endtabs %} +```` + +#### Stepper + +Use steppers for sequential, multi-step processes where order matters. + +**When to use:** Tutorials, installation guides, how-to guides, onboarding checklists, any sequential process. + +**Syntax:** + +```markdown +{% stepper %} +{% step %} +## First step + +Complete the initial setup by installing the required dependencies. +{% endstep %} + +{% step %} +## Second step + +Configure your environment variables in the `.env` file. +{% endstep %} + +{% step %} +## Third step + +Run the application with `npm start`. +{% endstep %} +{% endstepper %} +``` + +#### Hints + +Use hints to highlight important information without disrupting flow. Supported styles: `info`, `warning`, `danger`, `success`. + +**When to use:** Supplementary information, call-outs, best practices, warnings, troubleshooting tips. + +**Syntax:** + +```markdown +{% hint style="info" %} +This is an informational hint with helpful context. +{% endhint %} + +{% hint style="warning" %} +Be careful when running this command in production. +{% endhint %} + +{% hint style="danger" %} +This action cannot be undone. Make sure you have backups. +{% endhint %} + +{% hint style="success" %} +Your configuration has been saved successfully! +{% endhint %} +``` + +#### Expandable + +Use expandable sections for optional content that doesn't need to be visible by default. + +**When to use:** Optional deep-dives, advanced explanations, lengthy logs, FAQ answers, content that would clutter the page. + +**Syntax:** + +````markdown +
+Advanced Configuration Options + +Here you can find detailed information about advanced settings that most users won't need. + +```yaml +advanced: + option1: value1 + option2: value2 +``` +
+```` + +#### Columns + +Use columns to present content side-by-side (2 columns maximum). + +**When to use:** Side-by-side comparisons (pros vs cons), before/after examples, parallel instructions. + +**Syntax:** + +```markdown +{% columns %} +{% column %} +### Before + +Old implementation that was inefficient. +{% endcolumn %} + +{% column %} +### After + +New optimized approach with better performance. +{% endcolumn %} +{% endcolumns %} +``` + +#### Updates + +Use updates blocks for product updates, release notes, or changelogs. + +**When to use:** Changelog pages, release notes, version updates, product announcements. + +**Syntax:** + +```markdown +{% updates format="full" %} +{% update date="2024-01-15" %} +# Version 2.0 Released + +We've added new features including dark mode and improved search. +{% endupdate %} + +{% update date="2024-01-01" %} +# Bug Fixes + +Fixed several issues reported by the community. +{% endupdate %} +{% endupdates %} +``` + +#### Cards + +Use cards to create visual, clickable navigation elements. Cards are HTML tables with special attributes. + +**When to use:** Dashboards, feature overviews, linking to related pages, showcasing multiple resources. + +**Syntax:** + +```markdown +
+ + + + + + + + + + + + + + + + + + + + +
TitleTarget
Getting Started GuideQuick Start
API ReferenceAPI Docs
ExamplesCode Examples
+``` + +#### Embeds + +Use embeds to include external content like videos, interactive demos, or social media. + +**When to use:** Demonstration videos, interactive code sandboxes, tweets, external rich media. + +**Syntax:** + +```markdown +{% embed url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" %} + +{% embed url="https://codepen.io/username/pen/example" %} +``` + +#### Files + +Use file blocks to provide downloadable files with captions. + +**Syntax:** + +```markdown +{% file src="https://example.com/document.pdf" %} +Complete documentation in PDF format. +{% endfile %} +``` + +#### Buttons + +Use buttons for clear call-to-action links. Supported styles: `primary` and `secondary`. + +**When to use:** Download links, "Try it now" actions, external resource navigation. + +**Syntax:** + +```markdown +Download Now + +View Documentation +``` + +**Buttons with icons:** + +```markdown +View on GitHub +``` + +Icons use Font Awesome names (without the `fa-` prefix). + +#### Icons + +Inline icons from Font Awesome can enhance text readability. + +**When to use:** Visual indicators, status icons, improving scannability. + +**Syntax:** + +```markdown +check Feature enabled +warning Requires configuration +info Learn more +``` + +#### Reusable Content + +Reusable content blocks let you sync content across multiple pages. + +**When to use:** Call-to-actions, disclaimers, repeated instructions, any content that needs to stay consistent across pages. + +**Syntax:** + +```markdown +{% include "/reusable-content/rc12345" %} +``` + +Note: Reusable content blocks are different from pages. They're created through the GitBook UI and given unique IDs. + +#### OpenAPI Specifications + +OpenAPI specifications enable interactive, testable API documentation in GitBook. However, OpenAPI specs cannot be added directly to markdown files. + +**How to add OpenAPI specs:** + +OpenAPI specifications must be uploaded through one of these methods: + +1. **GitBook API** - Use the [OpenAPI endpoints](https://docs.gitbook.com/developers/gitbook-api/api-reference/openapi) to programmatically upload specs +2. **GitBook CLI** - Use the `gitbook openapi` command +3. **GitBook UI** - Upload specs through the web interface + +**Once uploaded**, you can reference API methods in your markdown using the OpenAPI block syntax: + +```markdown +{% openapi src="https://api.example.com/openapi.json" path="/users" method="get" %} +[https://api.example.com/openapi.json](https://api.example.com/openapi.json) +{% endopenapi %} +``` + +**Important notes:** + +* You cannot embed OpenAPI spec content directly in markdown files +* The `src` URL must point to an already-uploaded OpenAPI specification +* For more information, see the [GitBook OpenAPI documentation](https://docs.gitbook.com/api-references/openapi) + +### Nested Markdown in Custom Blocks + +Markdown formatting works inside custom block tags. Maintain standard markdown syntax within custom blocks: + +````markdown +{% tabs %} +{% tab title="Example" %} +This tab contains markdown: + +- Bullet points work + - Nested bullets too +- **Bold text** and *italic text* +- `inline code` + +```javascript +// Code blocks work too +const example = true; +``` +{% endtab %} +{% endtabs %} +```` + +### Common Pitfalls + +**File organization:** + +* Don't reference the same markdown file twice in SUMMARY.md +* Keep file paths consistent between SUMMARY.md and actual file locations +* Use relative paths consistently + +**Configuration conflicts:** + +* When using Git Sync, manage README.md only through your repository +* Keep .gitbook.yaml at the correct root level for your project +* Test redirects after moving or renaming files + +**Markdown formatting:** + +* Tables and columns are discouraged (use custom blocks instead) +* Avoid excessive nested lists (keep hierarchy simple) +* Don't mix tab/space indentation in SUMMARY.md + +**Custom blocks:** + +* Always close blocks properly (`{% endtab %}`, `{% endhint %}`, etc.) +* Match opening and closing tags exactly +* Test custom blocks in GitBook after editing locally + +### Working with Git Sync + +When GitBook is synced with Git: + +1. Changes in Git automatically update GitBook +2. Changes in GitBook automatically commit to Git +3. GitBook maintains SUMMARY.md based on UI edits +4. Merge conflicts should be resolved in Git + +**Best practices:** + +* Make structural changes (navigation) through SUMMARY.md in Git +* Make content changes either in Git or GitBook UI (be consistent) +* Review auto-generated commits from GitBook +* Use branch-based workflows for significant updates +* Test changes in a preview before merging to main + +### Example Complete Page + +Here's a complete example showing multiple GitBook features: + +```` +```markdown +# API Authentication Guide + +Learn how to authenticate with our API using API keys or OAuth 2.0. + +{% hint style="info" %} +All API requests require authentication. Choose the method that best fits your use case. +{% endhint %} + +## Authentication Methods + +{% tabs %} +{% tab title="API Key" %} +The simplest authentication method. Include your API key in the request header: +```bash +curl -H "X-API-Key: your-api-key" https://api.example.com/v1/users +``` + +{% hint style="warning" %} +Never commit API keys to version control. Use environment variables instead. +{% endhint %} +{% endtab %} + +{% tab title="OAuth 2.0" %} +More secure for user-facing applications: + +{% stepper %} +{% step %} +## Register your application +Get your client ID and secret from the developer dashboard. +{% endstep %} + +{% step %} +## Request authorization +Redirect users to our OAuth endpoint. +{% endstep %} + +{% step %} +Exchange code for token + +Use the authorization code to get an access token. +{% endstep %} +{% endstepper %} +{% endtab %} +{% endtabs %} + +## Rate Limits +{% columns %} +{% column %} +### Free Tier +1,000 requests/hour +10,000 requests/day +{% endcolumn %} + +{% column %} +### Pro Tier +10,000 requests/hour +100,000 requests/day +{% endcolumn %} +{% endcolumns %} +
+Need higher limits? + +Contact our sales team to discuss enterprise plans with custom rate limits and SLAs. +
+ +Get Started +```` diff --git a/.cursor/rules/writing-rules-style-guide.md b/.cursor/rules/writing-rules-style-guide.md new file mode 100644 index 000000000000..58560fc089dc --- /dev/null +++ b/.cursor/rules/writing-rules-style-guide.md @@ -0,0 +1,484 @@ +# Writing rules style guide + +## Audience (persona) + +If you reach for too many audiences, you'll miss them all. How you write to an advanced user will always differ from how you write to a novice. The same goes for personas. An AppSec user loves the power of Snyk, whereas a developer cares about ease of use within their workflow. + +- **Writing to a developer new to security?** Explain the basics clearly and provide easy-to-follow steps. + +- **Writing to a CISO looking for a new SAST?** Don't waste time on basic definitions. Show how Snyk overcomes the limitations of existing tools. + +## Core principles + +- **Write for scannability:** Users scan, they don't read. They decide quickly if content is relevant. Structure your content to help them, using clear headings, short paragraphs, and lists. + +- **Give the conclusion first (inverted pyramid):** Write the key points and answers first. This lets users get the most important information immediately and decide if they want to read the supporting details. + +- **Use headings as keywords:** Headings and subheadings should be short, use keywords users would search for, and help users understand the content at a glance. Avoid starting a topic with vague phrases like "This guide describes"; the title should make the topic clear. + +- **Use content chunks:** Use short, digestible paragraphs. Ensure there is enough white space between "chunks" to help users scan and identify what they need. + +- **Omit needless words:** Make every word count. Avoid filler words that don't add meaning. + - **Good:** Follow these steps to change your password. + - **Bad:** Follow these steps **in order to** change your password. + +## Global, inclusive, and bias-free communication + +Snyk reaches a global audience. Content must be respectful, inclusive, and easy to understand for everyone, including non-native English speakers. + +- **Inclusive language:** Do not use terms that may show bias regarding gender, race, culture, ability, or age. + + - Use gender-neutral terms (for example, "chairperson" instead of "chairman"). + + - Use "they/them" as the default non-gendered pronoun. + + - Portray people with disabilities positively. Use "people with disabilities" instead of "the disabled". + + - Use "allowlist" instead of "whitelist" and "blocklist" instead of "blacklist". + +- **Avoid slang, jargon, and idioms:** Avoid slang, jargon, local terms, and colloquialisms. Do not use U.S.-centric sports or military metaphors (for example, avoid "hit a home run" or "demilitarized zone"). + +- **Avoid non-English words:** Do not use Latin or other non-English phrases, even if they seem common. + + - Use "for example" instead of "e.g.". + + - Use "that is" instead of "i.e.". + + - Use "and so on" instead of "etc.". + + - Use "through" or "using" instead of "via". + +- **Language (US English):** Default to US English spelling and grammar. + + - **US:** analyze + + - **non-US:** analyse + +- **Be careful with art:** Images present globalization issues. Avoid hand signs, holiday themes, or specific flags that could be offensive or misunderstood in other cultures. + +## Accessibility + +Content must be easy for everyone to use, including people with disabilities. + +- **Provide alternative text (alt text):** All non-text elements (graphics, video) must have descriptive alternative (alt) text so they are accessible to screen readers. + +- **Don't use color alone:** Do not use color as the *only* way to convey information (for example, "click the green button"). This is inaccessible to users with color blindness. + +- **Avoid vague directional cues:** Do not use directional terms (like "left," "right," "above," or "below") as the *only* clue to location. This is confusing for users who rely on screen readers. + + - **Good:** In the **Save As** dialog box, click **OK**. + + - **Bad:** In the dialog box on the left, click **OK**. + +- **Document all keyboard shortcuts:** Document all keyboard shortcuts for users who cannot use a mouse. + +## Grammar, style, and tone + +### Active voice + +Use active voice and avoid passive voice. In active voice, the subject of the sentence does the action. + +- **Active (good):** Patch logged into the account. + +- **Active (good):** **You can** change your password. + +- **Passive (bad):** The account was logged into by Patch. + +- **Passive (bad):** **This functionality enables the users to** change their passwords. + +### Tense + +Use the present tense unless you have no choice. Avoid future tense like "will be" and imprecise words like "currently". + +- **Good:** After you click **Start**, the start screen appears. + +- **Bad:** After you click **Start**, the start screen **will appear**. + +### Pronouns + +- Write in the first person plural ("we," "us") or second person ("you") instead of "I". + +- When possible, avoid pronouns entirely by using imperatives (commands). + - **Best:** Click **Start** to begin the scan. + - **Good:** Now **we** can see the full list of vulnerabilities. + - **Bad:** Now **I** can see the full list of vulnerabilities. + +### Avoid modal verbs + +Modal verbs (may, should, might) add uncertainty. Use them sparingly. + +- **Good:** Snyk identifies vulnerabilities in your dependencies. + +- **Bad:** Snyk **should** identify vulnerabilities in your dependencies. + +### Avoid "please" + +Avoid using **please**. It is often unnecessary and can sound condescending. Use it only for situations that are inconvenient for the user (like waiting) or when the software is at fault. + +**Good:** Click **Save**. +**Bad:** **Please** click the **Save** button. + +### Avoid subjective and filler words + +Do not use subjective terms like **simply**, **easy**, or **fast**. What is easy for one user may be difficult for another. Avoid meaningless filler words like "just", "actually", or "literally". + +- **Good:** To publish, click **Publish to Web**. + +- **Bad:** To publish, **simply** click **Publish to Web**. + +### Brand possessives + +Avoid using possessives for brand names. + +- **Good:** The Priority Score feature in Snyk Code ranks vulnerabilities. + +- **Bad:** Snyk Code's Priority Score ranks vulnerabilities. + +### Lists + +List type + +- Use **bulleted lists** when order is unimportant. + +- Use **numbered lists** for a sequence of steps (procedures). + +Procedure steps + +Use the **imperative mood** (a command) for steps in a numbered list. + +**Good:** + +1. Click **Start**. + +2. Type your password. + +**Bad:** + +1. You **should click** the **Start** button. + +2. Then you **will type** your password. + +Parallel construction + +Use parallel construction for all list items. If you start one item with a verb, start all items with a verb of the same tense. + +- **Good:** Snyk can find vulnerabilities, suggest fixes, and recommend updates. + +- **Bad:** Snyk is great for finding vulnerabilities, base image update reporting, and secure coding. + +Punctuation and capitalization + +- If items are complete sentences, capitalize the first word and end with a period. + +- If items are fragments that complete the introductory sentence, start with a lowercase letter and use no end punctuation. + +- Do not add commas (,) or semicolons (;) to the end of list items. + +### Formatting and punctuation + +Placeholders + +Use *italics* for placeholder values that the user must replace with their own information. + +*Example:* git clone https://github.com/your-username/your-repo.git +*Example:* Go to Settings \> Organization \> *your-org-name*. + +Spacing + +Use **one space** after a period, not two. + +Ampersands (&) + +Do not use ampersands, unless required by a space limit. + +Apostrophes (') + +Do not use apostrophes in plurals of abbreviations or dates (for example, "APIs" or "1990s"). + +Colons (:) + +- Use colons to introduce lists. + +- When a colon is used in a sentence, the first word following it is lowercase unless it is a proper noun. + +- Capitalize the first word after a colon in a title. + +#### Commas (,) + +- Default to using the serial (Oxford) comma. + +- Avoid comma splices. + - **Good:** Snyk is a security platform. It helps developers code securely. + - **Bad:** Snyk is a security platform, it helps developers code securely. + +Dashes and hyphens + +- **Hyphen (-):** Use to combine words (for example, "client-side" or "read-only"). Do not hyphenate adverbs ending in -ly. + +- **En Dash (–):** Use to indicate a range, meaning "through" (for example, "pages 37–59" or "Dec 9–Jan 1"). + +- **Em Dash (—):** Use to create a strong break in a sentence. Put spaces on both sides of an em dash. + +Exclamation points (!) + +Use sparingly. Overexcitement reads as disingenuous. + +Semicolons (;) + +Use sparingly. They often signal an overcomplicated sentence. + +#### Plurals (s) + +Do not use parentheses (s) to indicate a plural. Use the plural form. + +- **Good:** ...displays one or more repositories. + +- **Bad:** ...displays the repository(s). + +### Word choice and usage + +Names + +- **Snyk:** Snyk **Projects** are always capitalized. + +- **Products:** Node.js, Composer, .NET, dep. + +- **Concepts:** Fintech, infrastructure as code (lowercase). + +Numbers + +- Spell out numbers one through nine. + +- Use numerals for 10 and greater. + +- **Exception:** Always use numerals for measurements (3 cm), time, or in lists with other numerals. + +- Spell out numbers that begin a sentence. + +Avoid "once" + +Avoid using "once" to mean "after." It can be confusing. + +- **Good:** **After** you enter the details, click **XYZ**. + +- **Bad:** **Once** you enter the details, click **XYZ**. + +Place "only" carefully + +"Only" comes immediately before the thing it limits. + +#### Simple > complex + +- Use "use" instead of "utilize". + +- Use "start" instead of "commence". + +- Use "before" instead of "prior to" or "in advance of". + +- Use "if" instead of "in the event that". + +- Use "ensure" instead of "make sure". + +- Use "first" instead of "first of all". + +- Use "and" instead of "and/or". + +Verbs and nouns (common pairs) + +Back up (v) / Backup (n, adj) + +- **Good:** You must **back up** your database. + +- **Good:** Create a **backup** file. + +Click (v) / Select (v) + +- **Good:** **Click Submit** (an action button). + +- **Good:** **Select** the **Enable** check box (an option). + +Log in (v) / Login (n) + +- **Good:** **Log in** to the Snyk Web UI. + +- **Good:** Use your **login** credentials. + +Set up (v) / Setup (n, adj) + +- **Good:** **Set up** your environment. + +- **Good:** The **setup** process is fast. + +Folder (n) / Directory (n) + +- **Good (UI):** Double-click the My Project **folder**. + +- **Good (CLI/Technical):** Change to the /lib **directory**. + +Compound words and hyphenation + +- Use client-side (adj); not client side (n) + +- Use cloud-native (adj); cloud native (n) + +- Use open-source (adj); open source (n) + +- Use server-side (adj); server side (n) + +- Use step-by-step (adj) + +- Use third-party (adj) + +- Use man-in-the-middle (adj) + +- Use same-origin policy (adj) + +- Use real time (n) + +- Use cheat sheet (n) + +- Use pull request (n) + +- Use white paper (n) + +- Use webhook (n) + +- Use codebase (n) + +- Use hard coded (adj) + +- Use username (n) + +- Use dropdown (n, adj) + +- Use lifecycle (n) + +- Use runtime (n, adj) + +### Documenting the user interface (UI) + +UI elements include all text on the screen, such as buttons, check boxes, menus, tabs, and window titles. + +Formatting UI elements + +Use **bold** to emphasize UI elements. Match the capitalization of the UI element exactly. + +- **Good:** Click **Start** to scan for vulnerabilities. + +- **Good:** Navigate to **ORGANIZATION SETTINGS**. + +- **Bad:** Click "Start" to scan for vulnerabilities. + +Be direct + +Do not include the name of the UI element type (like "button" or "tab") unless it is absolutely needed for clarity. + +- **Good:** Click **Update**. + +- **Bad:** Click the **Update** button. + +Describing navigation + +- Use Navigate to instead of "go to". + +- Use a greater-than symbol (>) with spaces to separate sequential UI steps. + - **Example:** Navigate to **Settings** > **Notifications**. + +### Links + +Add hyperlinks organically into sentences. + +- **Good:** Learn more in the Snyk IaC documentation. + +- **Bad:** **Click here** to learn more about Snyk IaC. + +### Messages (success, warnings, errors) + +- **Success:** A success message must tell the user what happened. If follow-up actions are needed, list them. + + - **Example:** Project monitoring was successfully stopped, but the webhook could not be removed. Ask the repository owner to delete the webhook. + +- **Warnings:** A warning message must tell the user what the problem is and how to fix it. + + - **Example:** This organization is at the limit of the Starter plan. Any new projects will be inactive. Please upgrade. + +- **Errors:** An error message must be informative. + + - **Example:** Sorry, the page could not be found. It might be an old link or it may have moved. + +### Abbreviations and acronyms + +- Spell out an abbreviation or acronym the first time you use it, followed by the short version in parentheses. + - **First use:** static application security testing (SAST) + - **Second use:** SAST + +- **Exception:** If the abbreviation is universally known (like API or HTML), you do not need to spell it out. + +- **CI/CD:** Use a slash, not a space. + +- See the Snyk Terms list for common acronyms. + +| | | | | | | | | +|----|----|----|----|----|----|----|----| +| **Original text** | **Rule** | **Explanation** | **URL** | **Display name** | **Original text is case-sensitive** | **Replacement text is lowercase at the start of a sentence** | **Context awareness** | +| **org;Org;organization** | Organization | Snyk Organizations are always capitalized. | | | TRUE | TRUE | | +| **Please** | | Redundant and used inconsistently. | | | TRUE | TRUE | | +| **code base** | codebase | Standardize as one word. | | | FALSE | FALSE | | +| **1** | one | Spell out single digits. | | | FALSE | FALSE | | +| **NodeJS** | Node.js | Standardize technical casing. | | | TRUE | TRUE | | +| **when it comes to** | | Redundant; remove. | | | FALSE | FALSE | | +| **Once** | after | Clearer and avoids cultural-specific ambiguity. | | | TRUE | TRUE | | +| **usage;utilize;utilization** | use | Shorter and simpler. | | | FALSE | FALSE | | +| **snyk app, snyk ui** | Snyk Web UI | | | | FALSE | FALSE | | +| **1000** | 1,000 | Use commas for thousands. | | | FALSE | FALSE | | +| **via** | through; using; by means of | Try replacing it with "through", "using", or "by means of". Via is a Latin term used more for geographical reasons. | | | FALSE | FALSE | | +| **7** | seven | Spell out single digits. | | | FALSE | FALSE | | +| **Just** | | Doesn't bring any value. | | | TRUE | TRUE | | +| **in this new era;in the ever-evolving landscape** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **snyk code** | Snyk Code | | | | FALSE | FALSE | | +| **pull-request** | pull request | | | | FALSE | FALSE | | +| **not to mention** | | Redundant; remove. | | | FALSE | FALSE | | +| **Is able to** | can | Shorter and simpler. | | | TRUE | TRUE | | +| **fintech** | FinTech | Standardize capitalization. | | | FALSE | FALSE | | +| **Delivering seamless and intuitive user experiences** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **she;he;he / she** | they;you | Use gender-neutral pronouns. | | | FALSE | FALSE | | +| **Driving innovation through cutting-edge technology** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **3** | three | Spell out single digits. | | | FALSE | FALSE | | +| **Within** | in | Shorter, simpler | | | FALSE | FALSE | | +| **devsecops** | DevSecOps | Standardize technical casing. | | | FALSE | FALSE | | +| **Is required to** | must | Shorter and simpler. | | | TRUE | TRUE | | +| **4** | four | Spell out single digits. | | | FALSE | FALSE | | +| **synergy** | | AI-sounding buzzword; avoid. | | | FALSE | FALSE | | +| **life cycle** | lifecycle | | | | FALSE | FALSE | | +| **snyk open source** | Snyk Open Source | | | | FALSE | FALSE | | +| **9** | nine | Spell out single digits. | | | FALSE | FALSE | | +| **group** | Group | Snyk Groups are always capitalized. | | | TRUE | TRUE | | +| **In the event that** | If | Shorter and simpler. | | | TRUE | TRUE | | +| **snyk** | Snyk | | | | FALSE | FALSE | | +| **black-list;blacklist** | denylist | Use inclusive language unless the software requires specific terms. | | | FALSE | FALSE | | +| **project** | Project | Snyk Projects are always capitalized. | | | TRUE | TRUE | | +| **resonates** | | Vague; consider removing. | | | FALSE | FALSE | | +| **appsec** | AppSec | Standardize technical casing. | | | FALSE | FALSE | | +| **&** | and | Avoid ampersands in body text. | | | FALSE | FALSE | | +| **actually;very;literally;really** | | Common superlatives that don't add value; remove. | | | FALSE | FALSE | | +| **Prior to;In advance of** | before | Clearer and simpler. | | | TRUE | TRUE | | +| **thereby;furthermore;Accordingly;therefore** | so | Overly academic; rework to be conversational. | | | FALSE | FALSE | | +| **white-list;whitelist** | allowlist | Use inclusive language unless the software requires specific terms. | | | FALSE | FALSE | | +| **2** | two | Spell out single digits. | | | FALSE | FALSE | | +| **step by step** | step-by-step | | | | FALSE | FALSE | | +| **snyk project** | Snyk Project | | | | FALSE | FALSE | | +| **5** | five | Spell out single digits. | | | FALSE | FALSE | | +| **e.g.** | for example | Avoid Latin abbreviations for non-Western readers. | | | TRUE | TRUE | | +| **8** | eight | Spell out single digits. | | | FALSE | FALSE | | +| **devops** | DevOps | Standardize technical casing. | | | FALSE | FALSE | | +| **N.B.** | note | Avoid Latin abbreviations for non-Western readers. | | | TRUE | TRUE | | +| **etc.;etc** | and so on | Avoids cultural-specific terms that may be confusing for non-Western readers. | | | FALSE | FALSE | | +| **AIBOM AiBOM AIBom** | AI-BOM | AI-BOM is the official Snyk-approved format; unless used in a command, then it's 'aibom'. | | | FALSE | FALSE | | +| **Leveraging advanced tools and methodologies** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **6** | six | Spell out single digits. | | | FALSE | FALSE | | +| **Snyk's** | Snyk | | | | FALSE | FALSE | | +| **In order to** | to | Shorter and simpler. | | | TRUE | TRUE | | +| **cross site scripting** | cross-site scripting | Standardize technical terms. | | | FALSE | FALSE | | +| **realtime** | real time | If used as a noun. | | | FALSE | FALSE | | +| **drop-down** | dropdown | | | | FALSE | FALSE | | +| **i.e** | that is | Avoid Latin abbreviations for non-Western readers. | | | TRUE | TRUE | | diff --git a/.cursor/rules/writing-style-guide.mdc b/.cursor/rules/writing-style-guide.mdc new file mode 100644 index 000000000000..012708c4d4a7 --- /dev/null +++ b/.cursor/rules/writing-style-guide.mdc @@ -0,0 +1,509 @@ +--- +description: Writing style guide for Snyk user docs +globs: "**/*.{md,mdx}" +alwaysApply: false +--- + +# Writing style guide + +When editing docs in this repo, follow the style guide in: + +- `.cursor/rules/writing-rules-style-guide.md` + +If you're about to make substantial edits to a doc page, read that file first and apply it to: + +- audience/persona and scannability +- global, inclusive, bias-free language +- accessibility (alt text, no color-only cues, avoid left/right/above/below references) +- grammar/tone (active voice, present tense, avoid filler) +- UI writing conventions (bold UI text, navigation with `Settings > Notifications`) +- preferred word choices and standard casing (see the replacements table) + +--- + +## Full style guide (reference) + +# Writing rules style guide + +## Audience (persona) + +If you reach for too many audiences, you'll miss them all. How you write to an advanced user will always differ from how you write to a novice. The same goes for personas. An AppSec user loves the power of Snyk, whereas a developer cares about ease of use within their workflow. + +- **Writing to a developer new to security?** Explain the basics clearly and provide easy-to-follow steps. + +- **Writing to a CISO looking for a new SAST?** Don't waste time on basic definitions. Show how Snyk overcomes the limitations of existing tools. + +## Core principles + +- **Write for scannability:** Users scan, they don't read. They decide quickly if content is relevant. Structure your content to help them, using clear headings, short paragraphs, and lists. + +- **Give the conclusion first (inverted pyramid):** Write the key points and answers first. This lets users get the most important information immediately and decide if they want to read the supporting details. + +- **Use headings as keywords:** Headings and subheadings should be short, use keywords users would search for, and help users understand the content at a glance. Avoid starting a topic with vague phrases like "This guide describes"; the title should make the topic clear. + +- **Use content chunks:** Use short, digestible paragraphs. Ensure there is enough white space between "chunks" to help users scan and identify what they need. + +- **Omit needless words:** Make every word count. Avoid filler words that don't add meaning. + - **Good:** Follow these steps to change your password. + - **Bad:** Follow these steps **in order to** change your password. + +## Global, inclusive, and bias-free communication + +Snyk reaches a global audience. Content must be respectful, inclusive, and easy to understand for everyone, including non-native English speakers. + +- **Inclusive language:** Do not use terms that may show bias regarding gender, race, culture, ability, or age. + + - Use gender-neutral terms (for example, "chairperson" instead of "chairman"). + + - Use "they/them" as the default non-gendered pronoun. + + - Portray people with disabilities positively. Use "people with disabilities" instead of "the disabled". + + - Use "allowlist" instead of "whitelist" and "blocklist" instead of "blacklist". + +- **Avoid slang, jargon, and idioms:** Avoid slang, jargon, local terms, and colloquialisms. Do not use U.S.-centric sports or military metaphors (for example, avoid "hit a home run" or "demilitarized zone"). + +- **Avoid non-English words:** Do not use Latin or other non-English phrases, even if they seem common. + + - Use "for example" instead of "e.g.". + + - Use "that is" instead of "i.e.". + + - Use "and so on" instead of "etc.". + + - Use "through" or "using" instead of "via". + +- **Language (US English):** Default to US English spelling and grammar. + + - **US:** analyze + + - **non-US:** analyse + +- **Be careful with art:** Images present globalization issues. Avoid hand signs, holiday themes, or specific flags that could be offensive or misunderstood in other cultures. + +## Accessibility + +Content must be easy for everyone to use, including people with disabilities. + +- **Provide alternative text (alt text):** All non-text elements (graphics, video) must have descriptive alternative (alt) text so they are accessible to screen readers. + +- **Don't use color alone:** Do not use color as the *only* way to convey information (for example, "click the green button"). This is inaccessible to users with color blindness. + +- **Avoid vague directional cues:** Do not use directional terms (like "left," "right," "above," or "below") as the *only* clue to location. This is confusing for users who rely on screen readers. + + - **Good:** In the **Save As** dialog box, click **OK**. + + - **Bad:** In the dialog box on the left, click **OK**. + +- **Document all keyboard shortcuts:** Document all keyboard shortcuts for users who cannot use a mouse. + +## Grammar, style, and tone + +### Active voice + +Use active voice and avoid passive voice. In active voice, the subject of the sentence does the action. + +- **Active (good):** Patch logged into the account. + +- **Active (good):** **You can** change your password. + +- **Passive (bad):** The account was logged into by Patch. + +- **Passive (bad):** **This functionality enables the users to** change their passwords. + +### Tense + +Use the present tense unless you have no choice. Avoid future tense like "will be" and imprecise words like "currently". + +- **Good:** After you click **Start**, the start screen appears. + +- **Bad:** After you click **Start**, the start screen **will appear**. + +### Pronouns + +- Write in the first person plural ("we," "us") or second person ("you") instead of "I". + +- When possible, avoid pronouns entirely by using imperatives (commands). + - **Best:** Click **Start** to begin the scan. + - **Good:** Now **we** can see the full list of vulnerabilities. + - **Bad:** Now **I** can see the full list of vulnerabilities. + +### Avoid modal verbs + +Modal verbs (may, should, might) add uncertainty. Use them sparingly. + +- **Good:** Snyk identifies vulnerabilities in your dependencies. + +- **Bad:** Snyk **should** identify vulnerabilities in your dependencies. + +### Avoid "please" + +Avoid using **please**. It is often unnecessary and can sound condescending. Use it only for situations that are inconvenient for the user (like waiting) or when the software is at fault. + +**Good:** Click **Save**. +**Bad:** **Please** click the **Save** button. + +### Avoid subjective and filler words + +Do not use subjective terms like **simply**, **easy**, or **fast**. What is easy for one user may be difficult for another. Avoid meaningless filler words like "just", "actually", or "literally". + +- **Good:** To publish, click **Publish to Web**. + +- **Bad:** To publish, **simply** click **Publish to Web**. + +### Brand possessives + +Avoid using possessives for brand names. + +- **Good:** The Priority Score feature in Snyk Code ranks vulnerabilities. + +- **Bad:** Snyk Code's Priority Score ranks vulnerabilities. + +### Lists + +List type + +- Use **bulleted lists** when order is unimportant. + +- Use **numbered lists** for a sequence of steps (procedures). + +Procedure steps + +Use the **imperative mood** (a command) for steps in a numbered list. + +**Good:** + +1. Click **Start**. + +2. Type your password. + +**Bad:** + +1. You **should click** the **Start** button. + +2. Then you **will type** your password. + +Parallel construction + +Use parallel construction for all list items. If you start one item with a verb, start all items with a verb of the same tense. + +- **Good:** Snyk can find vulnerabilities, suggest fixes, and recommend updates. + +- **Bad:** Snyk is great for finding vulnerabilities, base image update reporting, and secure coding. + +Punctuation and capitalization + +- If items are complete sentences, capitalize the first word and end with a period. + +- If items are fragments that complete the introductory sentence, start with a lowercase letter and use no end punctuation. + +- Do not add commas (,) or semicolons (;) to the end of list items. + +### Formatting and punctuation + +Placeholders + +Use *italics* for placeholder values that the user must replace with their own information. + +*Example:* git clone https://github.com/your-username/your-repo.git +*Example:* Go to Settings \> Organization \> *your-org-name*. + +Spacing + +Use **one space** after a period, not two. + +Ampersands (&) + +Do not use ampersands, unless required by a space limit. + +Apostrophes (') + +Do not use apostrophes in plurals of abbreviations or dates (for example, "APIs" or "1990s"). + +Colons (:) + +- Use colons to introduce lists. + +- When a colon is used in a sentence, the first word following it is lowercase unless it is a proper noun. + +- Capitalize the first word after a colon in a title. + +#### Commas (,) + +- Default to using the serial (Oxford) comma. + +- Avoid comma splices. + - **Good:** Snyk is a security platform. It helps developers code securely. + - **Bad:** Snyk is a security platform, it helps developers code securely. + +Dashes and hyphens + +- **Hyphen (-):** Use to combine words (for example, "client-side" or "read-only"). Do not hyphenate adverbs ending in -ly. + +- **En Dash (–):** Use to indicate a range, meaning "through" (for example, "pages 37–59" or "Dec 9–Jan 1"). + +- **Em Dash (—):** Use to create a strong break in a sentence. Put spaces on both sides of an em dash. + +Exclamation points (!) + +Use sparingly. Overexcitement reads as disingenuous. + +Semicolons (;) + +Use sparingly. They often signal an overcomplicated sentence. + +#### Plurals (s) + +Do not use parentheses (s) to indicate a plural. Use the plural form. + +- **Good:** ...displays one or more repositories. + +- **Bad:** ...displays the repository(s). + +### Word choice and usage + +Names + +- **Snyk:** Snyk **Projects** are always capitalized. + +- **Products:** Node.js, Composer, .NET, dep. + +- **Concepts:** Fintech, infrastructure as code (lowercase). + +Numbers + +- Spell out numbers one through nine. + +- Use numerals for 10 and greater. + +- **Exception:** Always use numerals for measurements (3 cm), time, or in lists with other numerals. + +- Spell out numbers that begin a sentence. + +Avoid "once" + +Avoid using "once" to mean "after." It can be confusing. + +- **Good:** **After** you enter the details, click **XYZ**. + +- **Bad:** **Once** you enter the details, click **XYZ**. + +Place "only" carefully + +"Only" comes immediately before the thing it limits. + +#### Simple > complex + +- Use "use" instead of "utilize". + +- Use "start" instead of "commence". + +- Use "before" instead of "prior to" or "in advance of". + +- Use "if" instead of "in the event that". + +- Use "ensure" instead of "make sure". + +- Use "first" instead of "first of all". + +- Use "and" instead of "and/or". + +Verbs and nouns (common pairs) + +Back up (v) / Backup (n, adj) + +- **Good:** You must **back up** your database. + +- **Good:** Create a **backup** file. + +Click (v) / Select (v) + +- **Good:** **Click Submit** (an action button). + +- **Good:** **Select** the **Enable** check box (an option). + +Log in (v) / Login (n) + +- **Good:** **Log in** to the Snyk Web UI. + +- **Good:** Use your **login** credentials. + +Set up (v) / Setup (n, adj) + +- **Good:** **Set up** your environment. + +- **Good:** The **setup** process is fast. + +Folder (n) / Directory (n) + +- **Good (UI):** Double-click the My Project **folder**. + +- **Good (CLI/Technical):** Change to the /lib **directory**. + +Compound words and hyphenation + +- Use client-side (adj); not client side (n) + +- Use cloud-native (adj); cloud native (n) + +- Use open-source (adj); open source (n) + +- Use server-side (adj); server side (n) + +- Use step-by-step (adj) + +- Use third-party (adj) + +- Use man-in-the-middle (adj) + +- Use same-origin policy (adj) + +- Use real time (n) + +- Use cheat sheet (n) + +- Use pull request (n) + +- Use white paper (n) + +- Use webhook (n) + +- Use codebase (n) + +- Use hard coded (adj) + +- Use username (n) + +- Use dropdown (n, adj) + +- Use lifecycle (n) + +- Use runtime (n, adj) + +### Documenting the user interface (UI) + +UI elements include all text on the screen, such as buttons, check boxes, menus, tabs, and window titles. + +Formatting UI elements + +Use **bold** to emphasize UI elements. Match the capitalization of the UI element exactly. + +- **Good:** Click **Start** to scan for vulnerabilities. + +- **Good:** Navigate to **ORGANIZATION SETTINGS**. + +- **Bad:** Click "Start" to scan for vulnerabilities. + +Be direct + +Do not include the name of the UI element type (like "button" or "tab") unless it is absolutely needed for clarity. + +- **Good:** Click **Update**. + +- **Bad:** Click the **Update** button. + +Describing navigation + +- Use Navigate to instead of "go to". + +- Use a greater-than symbol (>) with spaces to separate sequential UI steps. + - **Example:** Navigate to **Settings** > **Notifications**. + +### Links + +Add hyperlinks organically into sentences. + +- **Good:** Learn more in the Snyk IaC documentation. + +- **Bad:** **Click here** to learn more about Snyk IaC. + +### Messages (success, warnings, errors) + +- **Success:** A success message must tell the user what happened. If follow-up actions are needed, list them. + + - **Example:** Project monitoring was successfully stopped, but the webhook could not be removed. Ask the repository owner to delete the webhook. + +- **Warnings:** A warning message must tell the user what the problem is and how to fix it. + + - **Example:** This organization is at the limit of the Starter plan. Any new projects will be inactive. Please upgrade. + +- **Errors:** An error message must be informative. + + - **Example:** Sorry, the page could not be found. It might be an old link or it may have moved. + +### Abbreviations and acronyms + +- Spell out an abbreviation or acronym the first time you use it, followed by the short version in parentheses. + - **First use:** static application security testing (SAST) + - **Second use:** SAST + +- **Exception:** If the abbreviation is universally known (like API or HTML), you do not need to spell it out. + +- **CI/CD:** Use a slash, not a space. + +- See the Snyk Terms list for common acronyms. + +| | | | | | | | | +|----|----|----|----|----|----|----|----| +| **Original text** | **Rule** | **Explanation** | **URL** | **Display name** | **Original text is case-sensitive** | **Replacement text is lowercase at the start of a sentence** | **Context awareness** | +| **org;Org;organization** | Organization | Snyk Organizations are always capitalized. | | | TRUE | TRUE | | +| **Please** | | Redundant and used inconsistently. | | | TRUE | TRUE | | +| **code base** | codebase | Standardize as one word. | | | FALSE | FALSE | | +| **1** | one | Spell out single digits. | | | FALSE | FALSE | | +| **NodeJS** | Node.js | Standardize technical casing. | | | TRUE | TRUE | | +| **when it comes to** | | Redundant; remove. | | | FALSE | FALSE | | +| **Once** | after | Clearer and avoids cultural-specific ambiguity. | | | TRUE | TRUE | | +| **usage;utilize;utilization** | use | Shorter and simpler. | | | FALSE | FALSE | | +| **snyk app, snyk ui** | Snyk Web UI | | | | FALSE | FALSE | | +| **1000** | 1,000 | Use commas for thousands. | | | FALSE | FALSE | | +| **via** | through; using; by means of | Try replacing it with "through", "using", or "by means of". Via is a Latin term used more for geographical reasons. | | | FALSE | FALSE | | +| **7** | seven | Spell out single digits. | | | FALSE | FALSE | | +| **Just** | | Doesn't bring any value. | | | TRUE | TRUE | | +| **in this new era;in the ever-evolving landscape** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **snyk code** | Snyk Code | | | | FALSE | FALSE | | +| **pull-request** | pull request | | | | FALSE | FALSE | | +| **not to mention** | | Redundant; remove. | | | FALSE | FALSE | | +| **Is able to** | can | Shorter and simpler. | | | TRUE | TRUE | | +| **fintech** | FinTech | Standardize capitalization. | | | FALSE | FALSE | | +| **Delivering seamless and intuitive user experiences** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **she;he;he / she** | they;you | Use gender-neutral pronouns. | | | FALSE | FALSE | | +| **Driving innovation through cutting-edge technology** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **3** | three | Spell out single digits. | | | FALSE | FALSE | | +| **Within** | in | Shorter, simpler | | | FALSE | FALSE | | +| **devsecops** | DevSecOps | Standardize technical casing. | | | FALSE | FALSE | | +| **Is required to** | must | Shorter and simpler. | | | TRUE | TRUE | | +| **4** | four | Spell out single digits. | | | FALSE | FALSE | | +| **synergy** | | AI-sounding buzzword; avoid. | | | FALSE | FALSE | | +| **life cycle** | lifecycle | | | | FALSE | FALSE | | +| **snyk open source** | Snyk Open Source | | | | FALSE | FALSE | | +| **9** | nine | Spell out single digits. | | | FALSE | FALSE | | +| **group** | Group | Snyk Groups are always capitalized. | | | TRUE | TRUE | | +| **In the event that** | If | Shorter and simpler. | | | TRUE | TRUE | | +| **snyk** | Snyk | | | | FALSE | FALSE | | +| **black-list;blacklist** | denylist | Use inclusive language unless the software requires specific terms. | | | FALSE | FALSE | | +| **project** | Project | Snyk Projects are always capitalized. | | | TRUE | TRUE | | +| **resonates** | | Vague; consider removing. | | | FALSE | FALSE | | +| **appsec** | AppSec | Standardize technical casing. | | | FALSE | FALSE | | +| **&** | and | Avoid ampersands in body text. | | | FALSE | FALSE | | +| **actually;very;literally;really** | | Common superlatives that don't add value; remove. | | | FALSE | FALSE | | +| **Prior to;In advance of** | before | Clearer and simpler. | | | TRUE | TRUE | | +| **thereby;furthermore;Accordingly;therefore** | so | Overly academic; rework to be conversational. | | | FALSE | FALSE | | +| **white-list;whitelist** | allowlist | Use inclusive language unless the software requires specific terms. | | | FALSE | FALSE | | +| **2** | two | Spell out single digits. | | | FALSE | FALSE | | +| **step by step** | step-by-step | | | | FALSE | FALSE | | +| **snyk project** | Snyk Project | | | | FALSE | FALSE | | +| **5** | five | Spell out single digits. | | | FALSE | FALSE | | +| **e.g.** | for example | Avoid Latin abbreviations for non-Western readers. | | | TRUE | TRUE | | +| **8** | eight | Spell out single digits. | | | FALSE | FALSE | | +| **devops** | DevOps | Standardize technical casing. | | | FALSE | FALSE | | +| **N.B.** | note | Avoid Latin abbreviations for non-Western readers. | | | TRUE | TRUE | | +| **etc.;etc** | and so on | Avoids cultural-specific terms that may be confusing for non-Western readers. | | | FALSE | FALSE | | +| **AIBOM AiBOM AIBom** | AI-BOM | AI-BOM is the official Snyk-approved format; unless used in a command, then it's 'aibom'. | | | FALSE | FALSE | | +| **Leveraging advanced tools and methodologies** | | AI-sounding buzzwords; avoid. | | | FALSE | FALSE | | +| **6** | six | Spell out single digits. | | | FALSE | FALSE | | +| **Snyk's** | Snyk | | | | FALSE | FALSE | | +| **In order to** | to | Shorter and simpler. | | | TRUE | TRUE | | +| **cross site scripting** | cross-site scripting | Standardize technical terms. | | | FALSE | FALSE | | +| **realtime** | real time | If used as a noun. | | | FALSE | FALSE | | +| **drop-down** | dropdown | | | | FALSE | FALSE | | +| **i.e** | that is | Avoid Latin abbreviations for non-Western readers. | | | TRUE | TRUE | | diff --git a/.gitignore b/.gitignore index ab648a5f71ce..afb32d7a34d1 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,6 @@ **/.DS_Store .idea/ error-catalog/ + +# Snyk Security Extension - AI Rules (auto-generated) +.cursor/rules/snyk_rules.mdc