Contribuție la VaultPAM Help Center
Acest ghid explică cum să redactați și să editați articole în VaultPAM Help Center. Acesta acoperă vocea și tonul, structura articolului, convenții pentru capturi de ecran și procesul de PR. Nu aveți nevoie de un mediu de dezvoltare local pentru a propune o schimbare — editorul web GitHub este suficient pentru majoritatea editărilor.
1. Voce și ton
Scrieți pentru operator persona: un profesionist care gestionează accesul privilegiat zilnic și necesită răspunsuri precise și orientate pe sarcini, obținute rapid. Stilul de redactare urmează aceste principii:
- Orientat pe sarcini. Începeți cu obiectivul utilizatorului, nu cu teoria de bază. Puneți „ce" și „cum" înainte de „de ce".
- Persoana a doua. Adresați-vă cititorului ca „tu". Evitați „utilizatorul" sau „ar trebui să".
- Voce activă. „Faceți clic pe Connect" nu „Butonul Connect ar trebui să fie apăsat".
- Limbaj simplu. Preferiți propoziții scurte. Evitați jargonul, cu excepția terminologiei specifice VaultPAM care are deja un articol Concepts.
- Incluziv. Evitați idiomuri care nu se traduc bine. Scrieți într-un mod care funcționează în egală măsură pentru vorbitorii limbii engleze ca limbă maternă și ca limbă secundă.
- Specific. Denumiți elementele UI exacte în bold (
**Save**, tab-ul**Connectors**). Includeți mesajele de eroare exacte în blocuri de cod.
Hartă de persoane
| Persoane | Cine sunt | Schimbare de ton |
|---|---|---|
| Evaluator | Tocmai s-au înscris; prima sesiune | Ajutor suplimentar; adăugați liste de verificare „Înainte de a începe" |
| Operator | Utilizator zilnic; lansare de sesiuni, aprobări | Concis; cunosc produsul |
| Admin | Configurarea organizațiilor, politicilor, MFA | Precis; au nevoie de nume și valori de câmp exacte |
| Self-hosted Admin | Admin în spatele unui firewall | Notați constrângerile offline; marcați funcțiile doar pentru cloud |
| Support Engineer | Rezolvarea tichetelor | Secțiuni adânc linkabile; includeți coduri de eroare exacte |
2. Structura articolului
Fiecare articol trebuie să includă blocul frontmatter și să urmeze ordinea secțiunilor de mai jos.
Frontmatter (obligatoriu)
---
title: Titlu scurt, imperativ (de exemplu, „Conectați un Connector")
description: Rezumat pe o singură linie pentru SEO și indexul de căutare.
persona: operator # una dintre: evaluator, operator, admin, self-hosted-admin, support
category: how-to # una dintre: 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]
---
Toate șase câmpuri sunt obligatorii. Pipeline-ul de construire emite o avertizare pentru orice câmp lipsă. Odată ce fluxul de lucru de redactare este matur, poarta CI va trata avertizările ca erori.
Ordinea secțiunilor
- Titlu (H1) — se potrivește cu
titledin frontmatter. - Paragraf rezumat scurt — 1–3 propoziții: ce va realiza cititorul și când să folosească acest articol. Fără titlu H2.
- Înainte de a începe (opțional H2) — condiții preliminare, permisiuni necesare, linkuri la articole de configurare. Folosiți o listă de verificare (
- [ ]). - Pași (H2 pentru fiecare sarcină majoră) — pași numerotați (
1.,2., …). O acțiune per pas. Puneți rezultatul așteptat la sfârșitul unui pas când nu este evident. - Depanare (opțional H2) — listă de perechi „Problemă / Soluție". Folosiți stil de listă de definiții sau tabel.
- Articole conexe (opțional H2) — 3–5 linkuri cu glonț la documentele conexe. Folosiți linkuri relative la site (
[Add a Safe](/how-to/add-safe)etc.).
Schelet de exemplu
---
title: Aprobați o cerere de sesiune
description: Cum să aprobați sau să respingeți o cerere de aprobare a unei sesiuni RDP în VaultPAM.
persona: operator
category: how-to
last_reviewed: "2026-05-12"
applies_to_versions: ["v1"]
keywords: [approval, session, rdp]
---
# Aprobați o cerere de sesiune
Când un utilizator solicită o sesiune RDP care necesită aprobare, primiți o notificare în VaultPAM. Acest articol vă arată cum să revizuiți și să aprobați sau să respingeți acea cerere.
## Înainte de a începe
- [ ] Aveți rolul **Approver** în Safe-ul relevant.
- [ ] Cererea de sesiune nu a expirat (TTL implicit: 10 minute).
## Aprobați cererea
1. Deschideți **VaultPAM** și faceți clic pe **Approvals** în bara laterală.
2. Localizați cererea în așteptare și faceți clic pe **Review**.
3. Verificați câmpurile **Target**, **Requester** și **Justification**.
4. Faceți clic pe **Approve** sau **Reject**.
Solicitantul primește o notificare în aplicație imediat.
## Depanare
**Meniul Approvals lipsește.**
Nu aveți rolul Approver. Cereți administratorului VaultPAM să vă adauge ca aprobator în Safe-ul relevant.
## Articole conexe
- [Ce este un Safe?](/concepts/what-is-a-safe)
- [Aprobați o sesiune în așteptare](/how-to/approve-session)
- [Partajați o înregistrare](/how-to/share-recording)
3. Convenții pentru capturi de ecran
Capturile de ecran ajută operatorii să recunoască elementul UI corect într-o privire. Urmați aceste reguli pentru a menține capturile de ecran ușor de întreținut și accesibile.
| Regulă | Detaliu |
|---|---|
| Format | Doar PNG. Nu folosiți JPEG sau WebP (artefactele de compresie ascund textul UI). |
| Lățime maximă | 1024 px. Exportați la densitate de pixeli 1x (nu 2x/Retina) pentru a menține dimensiunea fișierului sub 200 KB. |
| Decupare strânsă | Arătați doar zona relevantă. Evitați capturile de ecran cu browserul complet, cu excepția cazului în care contextul viewport-ului complet este necesar. |
| Mascare date sensibile | Estompați sau înlocuiți orice nume de host, adrese IP, nume de utilizatori sau token-uri vizibile în captură. Folosiți o cutie de culoare solidă, nu suprapunere de text. |
| Text alternativ | Obligatoriu pe fiecare imagine. Descrieți ce arată captura de ecran, nu ce doriți cititorului să facă. Exemplu: Captură de ecran a panoului Approvals arătând o cerere în așteptare cu un buton Approve. |
| Denumire fișier | [article-slug]-[step-number]-[short-label].png, de exemplu, connect-connector-01-enrollment-token.png. |
| Cale de stocare | Plasați imaginile în docs/help/img/[article-slug]/. |
Markdown pentru imagine
4. Proces PR
Opțiunea A — Editați prin editorul web GitHub (recomandat pentru schimbări doar de conținut)
Fiecare articol publicat are un link Edit this page la jos. Făcând clic pe el se deschide editorul web GitHub pre-completat cu fișierul și ramura corectă.
- Faceți clic pe Edit this page la jos în articol.
- Faceți modificările în editor.
- În panoul Propose changes, scrieți un mesaj de commit scurt (de exemplu,
fix typo in session approval steps). - Faceți clic pe Propose changes → Create pull request.
- În formularul PR, setați titlul pentru a descrie schimbarea (de exemplu,
Fix typo in approve-session article). Niciun cod de problemă nu este necesar pentru reparații pure de conținut. - Trimiteți PR-ul. Un comentariu de previzualizare este postat automat cu URL-ul dev docs cu ámbitus PR la
https://dev.euwarden.com/docs/pr-<n>/— linkul apare în PR în câteva minute.
Opțiunea B — Ramificație dintr-o problemă Jira (pentru lucru structurat la caracteristici sau reproiectări)
Când o schimbare help-center este urmărită sub o problemă Jira (de exemplu, adăugarea unui articol nou legat de o lansare de caracteristici):
- Nume de ramură:
AIC-XXXX-help-<slug>(de exemplu,AIC-1234-help-connector-offline-guide). - Prefix de mesaj de commit:
AIC-XXXX: <description>. - Titlu PR:
[AIC-XXXX] Add connector-offline troubleshooting article.
PR-urile doar pentru docs (fără schimbări de cod) pot ținti main direct. Codul de problemă Jira este opțional pentru reparații de litere/fraze.
Revizuire și îmbinare
CODEOWNERS solicită automat revizuire de la @OWL-Management/product-analysts și @OWL-Management/pm pentru toate PR-urile care ating docs/help/**. Un PR trebuie să primească cel puțin o aprobare înainte de a putea fi îmbinat.
SLA de revizuire: revizorii de conținut se străduiesc să răspundă în maximum 2 zile lucrătoare. Dacă un PR este urgent (de exemplu, corectarea unei inexactități care blochează suportul), adăugați etichetă help-urgent și ping-uiți canalul Slack #docs.
URL de previzualizare
Fiecare PR care modifică docs/help/** sau docs-site/** declanșează o construire de previzualizare. CI postează URL-ul dev docs cu ámbitus PR (https://dev.euwarden.com/docs/pr-<n>/) ca comentariu PR lipicios în aproximativ 3 minute.
Mediile de previzualizare nu sunt indexate de motoarele de căutare (eticheta meta noindex este setată).
5. Listă de verificare înainte de a trimite un PR
- Frontmatter are toate șase câmpuri obligatorii:
title,description,persona,category,last_reviewed,applies_to_versions. -
last_reviewedeste data de astazi. - Toate capturile de ecran sunt PNG, max 1024 px lățime, cu text alternativ.
- Datele sensibile din capturi de ecran sunt mascate.
- Titlurile urmează ordinea secțiunilor (fără H1 în interiorul unui bloc de pași).
- Link-urile interne folosesc căi relative la site (încep cu
/). - Fără linkuri rupte (construirea Docusaurus va avertiza pe linkuri rupte).
- URL de previzualizare verificat și articolul se redă corect.