Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
194 lines (135 loc) · 6.46 KB

CONTRIBUTING.md

File metadata and controls

194 lines (135 loc) · 6.46 KB
Raw

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 43 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.

Add DOCS_PRODUCT_LATEST_ONLY=true to also restrict the build to that product's latest version only (default false builds all versions).

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.