Contributing to VaultPAM Help Center
This guide explains how to write and edit articles in the VaultPAM Help Center. It covers voice and tone, article structure, screenshot conventions, and the PR process. You do not need a local development environment to propose a change — the GitHub web editor is sufficient for most edits.
1. Voice and tone
Write for the operator persona: a practitioner who manages privileged access day-to-day and needs accurate, task-oriented answers quickly. The writing style follows these principles:
- Task-oriented. Start with the user's goal, not with background theory. Put the "what" and "how" before the "why".
- Second person. Address the reader as "you". Avoid "the user" or "one should".
- Active voice. "Click Connect" not "The Connect button should be clicked".
- Plain language. Prefer short sentences. Avoid jargon unless it is VaultPAM-specific terminology that already has a Concepts article.
- Inclusive. Avoid idioms that do not translate well. Write in a way that works equally for speakers of English as a first and second language.
- Specific. Name exact UI elements in bold (
**Save**,**Connectors**tab). Include exact error messages in code blocks.
Persona map
| Persona | Who they are | Tone shift |
|---|---|---|
| Evaluator | Just signed up; first session | Extra hand-holding; add "Before you begin" checklists |
| Operator | Daily user; launching sessions, approvals | Concise; they know the product |
| Admin | Configuring orgs, policies, MFA | Precise; they need exact field names and values |
| Self-hosted Admin | Admin behind a firewall | Note offline constraints; flag cloud-only features |
| Support Engineer | Resolving tickets | Deep-linkable sections; include exact error codes |
2. Article structure
Every article must include the frontmatter block and follow the section order below.
Frontmatter (required)
---
title: Short, imperative title (e.g., "Connect a Connector")
description: One-sentence summary for SEO and the search index.
persona: operator # one of: evaluator, operator, admin, self-hosted-admin, support
category: how-to # one of: get-started, how-to, concepts, reference, troubleshooting, release-notes, security-compliance, admin
last_reviewed: "YYYY-MM-DD"
applies_to_versions: ["v1"]
keywords: [connector, rdp, session]
---
All six fields are required. The build pipeline emits a warning for any missing field. Once the authoring workflow is mature, the CI gate will treat warnings as errors.
Section order
- Title (H1) — matches the frontmatter
title. - Short summary paragraph — 1–3 sentences: what the reader will accomplish and when to use this article. No H2 heading.
- Before you begin (optional H2) — prerequisites, required permissions, links to setup articles. Use a checklist (
- [ ]). - Steps (H2 for each major task) — numbered steps (
1.,2., …). One action per step. Put the expected outcome at the end of a step when it is not obvious. - Troubleshooting (optional H2) — list of "Problem / Solution" pairs. Use a definition-list style or a table.
- Related articles (optional H2) — 3–5 bullet links to related docs. Use site-relative links (
[Add a Safe](/how-to/add-safe)etc.).
Example skeleton
---
title: Approve a Session Request
description: How to approve or reject an incoming RDP session approval request in VaultPAM.
persona: operator
category: how-to
last_reviewed: "2026-05-12"
applies_to_versions: ["v1"]
keywords: [approval, session, rdp]
---
# Approve a Session Request
When a user requests an RDP session that requires approval, you receive a notification in VaultPAM. This article shows you how to review and approve or reject that request.
## Before you begin
- [ ] You have the **Approver** role in the relevant Safe.
- [ ] The session request has not expired (default TTL: 10 minutes).
## Approve the request
1. Open **VaultPAM** and click **Approvals** in the sidebar.
2. Locate the pending request and click **Review**.
3. Check the **Target**, **Requester**, and **Justification** fields.
4. Click **Approve** or **Reject**.
The requester receives an in-app notification immediately.
## Troubleshooting
**The Approvals menu is missing.**
You do not have the Approver role. Ask your VaultPAM admin to add you as an approver on the relevant Safe.
## Related articles
- [What is a Safe?](/concepts/what-is-a-safe)
- [Approve a pending session](/how-to/approve-session)
- [Share a recording](/how-to/share-recording)
3. Screenshot conventions
Screenshots help operators recognise the correct UI element at a glance. Follow these rules to keep screenshots maintainable and accessible.
| Rule | Detail |
|---|---|
| Format | PNG only. Do not use JPEG or WebP (compression artifacts obscure UI text). |
| Maximum width | 1024 px. Export at 1x pixel density (not 2x/Retina) to keep file size under 200 KB. |
| Crop tightly | Show only the relevant area. Avoid full-browser screenshots unless the full viewport context is needed. |
| Mask sensitive data | Blur or replace any hostnames, IP addresses, usernames, or tokens visible in the screenshot. Use a solid colour box, not text overlay. |
| Alt text | Required on every image. Describe what the screenshot shows, not what you want the reader to do. Example: Screenshot of the Approvals panel showing one pending request with an Approve button. |
| File naming | [article-slug]-[step-number]-[short-label].png, e.g., connect-connector-01-enrollment-token.png. |
| Storage path | Place images in docs/help/img/[article-slug]/. |
Image markdown
4. PR process
Option A — Edit via GitHub web editor (recommended for content-only changes)
Every published article has an Edit this page link at the bottom. Clicking it opens the GitHub web editor pre-filled with the correct file and branch.
- Click Edit this page at the bottom of the article.
- Make your changes in the editor.
- In the Propose changes panel, write a short commit message (e.g.,
fix typo in session approval steps). - Click Propose changes → Create pull request.
- In the PR form, set the title to describe the change (e.g.,
Fix typo in approve-session article). No issue key is required for pure content fixes. - Submit the PR. A preview environment is deployed automatically at
pr-<n>.docs-preview.aiforja.com— the URL appears as a comment on the PR within a few minutes.
Option B — Branch from a Jira issue (for structured feature or redesign work)
When a help-center change is tracked under a Jira issue (e.g., adding a new article tied to a feature release):
- Branch name:
AIC-XXXX-help-<slug>(e.g.,AIC-1234-help-connector-offline-guide). - Commit message prefix:
AIC-XXXX: <description>. - PR title:
[AIC-XXXX] Add connector-offline troubleshooting article.
Docs-only PRs (no code changes) may target main directly. Jira issue key is optional for typo/phrasing fixes.
Review and merge
CODEOWNERS automatically requests review from @OWL-Management/product-analysts and @OWL-Management/pm for all PRs that touch docs/help/**. A PR must receive at least one approval before it can be merged.
Review SLA: content reviewers aim to respond within 2 business days. If a PR is urgent (e.g., fixing a support-blocking inaccuracy), add the help-urgent label and ping the #docs Slack channel.
Preview URL
Every PR that modifies docs/help/** or docs-site/** triggers a preview build. The preview URL (pr-<n>.docs-preview.aiforja.com) is posted as a sticky PR comment by CI within about 3 minutes. The preview is torn down automatically when the PR is merged or closed.
Preview environments are not indexed by search engines (noindex meta tag is set).
5. Checklist before submitting a PR
- Frontmatter has all six required fields:
title,description,persona,category,last_reviewed,applies_to_versions. -
last_reviewedis today's date. - All screenshots are PNG, max 1024 px wide, with alt text.
- Sensitive data in screenshots is masked.
- Headings follow the section order (no H1 inside a step block).
- Internal links use site-relative paths (start with
/). - No broken links (Docusaurus build will warn on broken links).
- Preview URL checked and article renders correctly.