Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
192 lines (134 loc) · 6.32 KB

CONTRIBUTING.md

File metadata and controls

192 lines (134 loc) · 6.32 KB

Contributing to Netwrix Documentation

Thank you for contributing to Netwrix product documentation. This guide covers everything you need to get started.

Prerequisites

  • Node.js 22+
  • npm
  • Git
  • Vale (style linter — optional for local use; issues are auto-fixed on PRs)

Install Vale

Vale is a command-line linter for prose. It checks your writing against a set of style rules — like a spell checker, but for grammar, word choice, and tone. Vale issues are auto-fixed on PRs, but you can install it locally to preview issues before pushing.

macOS:

brew install vale

Linux:

sudo snap install vale

Windows:

choco install vale

Manual install for any platform:

Download the latest release from github.com/errata-ai/vale/releases, extract the binary, and add it to your PATH.

Verify the installation:

vale --version

Getting started

# Clone the repository
git clone https://github.com/netwrix/docs.git
cd docs

# Install dependencies
npm install

# Start development server
npm run start

The dev server runs on port 4500 with hot reload — changes you make to documentation files appear immediately in the browser.

Workflow

  1. Create a branch from dev (never commit directly to dev or main).
  2. Make your changes to documentation files in docs/.
  3. Optionally run Vale on your changed files to preview issues (they'll be auto-fixed on the PR).
  4. Test the build with npm run build.
  5. Push your branch.
  6. Create a pull request (PR) targeting dev.

After you open a PR, Vale and Dale issues are auto-fixed and a summary is posted. An editorial review also runs and posts results as a PR comment. To get help with editorial suggestions, comment @claude on the PR followed by your request.

Writing standards

See netwrix_style_guide.md in the project root for the full style guide covering voice, tone, formatting, and terminology.

Images

  • Location: static/img/product_docs/<product>/
  • Format: .webp
  • Paths: Always absolute from project root
![Description](/img/product_docs/productname/image.webp)

Frontmatter

Every documentation page needs frontmatter:

---
title: 'Page Title'
sidebar_label: 'Sidebar Label'
description: 'SEO description'
---

Linting with Vale

Vale enforces 30 Netwrix-specific rules covering word choice, punctuation, formatting, and common writing issues. Vale issues are auto-fixed on PRs, but you can run it locally to preview:

vale docs/path/to/file.md

Run Vale on all changed files compared to dev:

git diff --name-only dev | grep '^docs/.*\.md$' | xargs vale

File structure

  • docs/<product>/<version>/ — Versioned product documentation (e.g., docs/accessanalyzer/12.0/)
  • docs/<product>/ — Single-version (SaaS) products
  • docs/kb/ — Knowledge base articles (canonical source; never manually copy into versioned folders)
  • static/img/product_docs/<product>/ — Product images
  • sidebars/<product>/<version>.js — Sidebar configs (auto-generated; rarely need manual editing)

Edits to one version don't propagate to others. Update each version that needs the change explicitly.

Available commands

npm run start            # Dev server on port 4500
npm run start-chok       # Dev server with polling (for network drives)
npm run build            # Full production build
npm run clear            # Clear Docusaurus cache (fixes stale build issues)
npm run serve            # Serve production build

Building a single product

You can build or run documentation for a single product using the DOCS_PRODUCT environment variable, which speeds up development:

Windows (PowerShell):

$ENV:DOCS_PRODUCT="pingcastle"
npm run start

Unix/Linux/macOS:

export DOCS_PRODUCT="pingcastle"
npm run start

Available product IDs are in src/config/products.js.

Using Claude Code

If you have Claude Code installed, this repository includes skills and agents that can help with documentation work. These are entirely optional — you don't need Claude Code to contribute.

Linting with Dale

Dale is an AI linter that catches context-dependent issues that regex-based Vale can't — passive voice, misplaced modifiers, idioms, wordiness, and other patterns. Dale issues are auto-fixed on PRs alongside Vale.

Run Dale locally on any markdown file to preview context-dependent issues:

/dale docs/path/to/file.md

Get interactive writing help

Ask Claude Code for help with your writing — brainstorming document structure, drafting a section, editing existing content, or understanding a style rule. Claude automatically uses the doc-help skill when you ask for writing assistance. You can also invoke it directly with /doc-help, followed by your request.

Run autonomous documentation tasks

For well-defined tasks where the work is clear and doesn't need back-and-forth, Claude automatically uses the tech-writer agent to handle the work end-to-end.

Examples:

  • "Fix all the Vale errors in docs/accessanalyzer/12.0/install.md".
  • "Edit this procedure for clarity and Netwrix style".
  • "Draft the installation steps based on this outline: [outline]"

For tasks that need design decisions first — like writing a new guide from scratch — Claude uses doc-help to brainstorm the structure with you, then hands the drafting off to the tech-writer agent.

Quick reference

Task Tool
Quick lint check on a file /dale docs/path/to/file.md
Plan structure for a new document doc-help then tech-writer agent
Review or improve existing content doc-help
Fix Vale errors across a file tech-writer agent
Edit a file for style and clarity tech-writer agent
Understand a style rule or convention doc-help

Common Mistakes

  • Don't manually copy KB content into versioned product folders — it's managed by the KB script.
  • Vale issues are auto-fixed on PRs, but running Vale locally helps catch issues early.
  • Don't commit directly to dev or main — create a branch from dev first.
  • Don't target main in PRs — always use dev.
  • Don't use first person anywhere in documentation content.
  • Don't omit examples — every concept introduced needs one.