Contributing to the F5 Technical Writing Style Guide

This guide is a living document. Contributions from writers, editors, and subject matter experts are welcome.

Before you contribute

• Read the README.md for an overview of the guide's purpose, fallback style guides, and language conventions.
• All content must follow American English spelling and conventions. Use the American Heritage Dictionary as the spelling reference when in doubt.
• Check the TOC.md to see if a guideline already exists before adding a new one.

How to add or update a guideline

1. Create a branch from main using the naming convention feat/your-topic-name.
2. Use the template in templates/guideline-template.md for all new files.
3. Place your file in the appropriate category folder:
   • accessibility/ — accessibility standards
   • error-messages/ — error message writing and publishing guidelines
   • formatting/ — visual and structural formatting rules
   • grammar/ — grammar rules and usage
   • procedures/ — rules for writing tasks and instructions
   • punctuation/ — punctuation usage
   • terminology/ — word choice and specific term guidance
   • voice-and-tone/ — tone, style, and language principles
4. Update TOC.md to include your new file in alphabetical order within its section.
5. Update the Related section of any existing files that are relevant to your new guideline.
6. Link your MR to a Jira ticket. For minor fixes and typos, use the catch-all housekeeping ticket.
7. All MRs require at least one reviewer approval before merging into main.

Sync changes to downstream repos

This repo is included as a submodule in downstream documentation repos. A GitHub Actions workflow automatically opens a PR in each downstream repo when style guide changes merge to main.

The sync is not triggered on every merge -- only when the PR includes the sync-downstream label. Add this label when your changes should propagate to downstream repos. Leave it off for housekeeping changes like README updates or minor formatting fixes.

If you merge a PR without the label and need to trigger the sync manually, go to Actions > Sync style guide submodule > Run workflow in this repo.

When to use the sync-downstream label

Use the label when your PR:

• Adds or updates a style guideline
• Adds or updates a document template
• Makes a change that contributors in downstream repos need to be aware of

Don't use the label when your PR:

• Updates repo documentation (README, CONTRIBUTING, TOC)
• Fixes a typo or formatting issue with no impact on the guidance itself
• Makes changes to workflow or tooling files

Guideline file standards

• One file = one guideline or term. If you can't describe the file's scope in a single sentence, it's probably two files.
• Complete all frontmatter fields. Do not leave title or category blank.
• Set last-reviewed to the date you created or last updated the file (YYYY-MM-DD format).
• The Guidance section should be two to three sentences maximum. Lead with the rule, not the exception.
• Examples are required. Every guideline needs at least one Do and one Don't.
• The Notes section is optional. Omit it if there's nothing to add — an empty section is worse than no section.

Style decisions and conflicts

If you identify a conflict between this guide and a fallback guide (Microsoft Style Guide, Chicago Manual of Style), document the conflict in the Notes section and note which authority this guide follows and why.

If you identify a conflict between this guide and a product-specific style convention, raise it for discussion before merging. Governance for style decisions sits at the content strategy level.

Questions

Open an issue in this repo or post in #doc-reviews on Slack.