Contribuire al VaultPAM Help Center
Questa guida spiega come redarre e modificare articoli nel VaultPAM Help Center. Copre il tono di voce, la struttura degli articoli, le convenzioni per gli screenshot e il processo PR. Non è necessario disporre di un ambiente di sviluppo locale per proporre una modifica — l'editor web di GitHub è sufficiente per la maggior parte degli interventi di editing.
1. Tono di voce
Scrivete per la persona operator: un professionista che gestisce l'accesso privilegiato quotidianamente e ha bisogno di risposte accurate e orientate al compito rapidamente. Lo stile di scrittura segue questi principi:
- Orientato al compito. Iniziate con l'obiettivo dell'utente, non con la teoria di base. Mettete il "cosa" e il "come" prima del "perché".
- Seconda persona. Rivolgevi al lettore con "voi". Evitate "l'utente" o "si dovrebbe".
- Voce attiva. "Cliccate su Connetti" e non "Il pulsante Connetti deve essere cliccato".
- Linguaggio semplice. Preferite frasi brevi. Evitate il gergo a meno che non sia terminologia specifica di VaultPAM che ha già un articolo nella sezione Concetti.
- Inclusivo. Evitate idiomi che non si traducono bene. Scrivete in modo che funzioni equamente per i parlanti di inglese come prima e seconda lingua.
- Specifico. Nominate gli elementi UI esatti in grassetto (
**Salva**, scheda**Connettori**). Includete i messaggi di errore esatti nei blocchi di codice.
Mappa delle persone
| Persona | Chi sono | Adattamento del tono |
|---|---|---|
| Valutatore | Appena registrato; prima sessione | Supporto extra; aggiungere elenchi di controllo "Prima di iniziare" |
| Operatore | Utente quotidiano; lanciamento di sessioni, approvazioni | Conciso; conosce il prodotto |
| Admin | Configurazione di organizzazioni, policy, MFA | Preciso; ha bisogno di nomi e valori esatti dei campi |
| Self-hosted Admin | Admin dietro un firewall | Notare vincoli offline; segnalare funzioni solo cloud |
| Support Engineer | Risoluzione di ticket | Sezioni linkabili in profondità; includere codici di errore esatti |
2. Struttura dell'articolo
Ogni articolo deve includere il blocco frontmatter e seguire l'ordine delle sezioni sottostante.
Frontmatter (obbligatorio)
---
title: Titolo breve, imperativo (es., "Connettere un Connector")
description: Riassunto in una frase per SEO e l'indice di ricerca.
persona: operator # uno di: evaluator, operator, admin, self-hosted-admin, support
category: how-to # uno di: 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]
---
Tutti e sei i campi sono obbligatori. La pipeline di build emette un avvertimento per qualsiasi campo mancante. Una volta che il flusso di lavoro di authoring sarà maturo, il gate CI tratterà gli avvertimenti come errori.
Ordine delle sezioni
- Titolo (H1) — corrisponde al
titlenel frontmatter. - Breve paragrafo di sintesi — 1–3 frasi: cosa il lettore realizzerà e quando utilizzare questo articolo. Nessun heading H2.
- Prima di iniziare (H2 facoltativo) — prerequisiti, permessi richiesti, link agli articoli di configurazione. Utilizzate un elenco di controllo (
- [ ]). - Passaggi (H2 per ogni compito principale) — passaggi numerati (
1.,2., …). Un'azione per passaggio. Mettete il risultato atteso alla fine di un passaggio quando non è ovvio. - Risoluzione dei problemi (H2 facoltativo) — elenco di coppie "Problema / Soluzione". Utilizzate lo stile di elenco di definizioni o una tabella.
- Articoli correlati (H2 facoltativo) — 3–5 link a elenchi puntati di documenti correlati. Utilizzate link relativi al sito (
[Aggiungere un Safe](/how-to/add-safe)ecc.).
Scheletro di esempio
---
title: Approvare una Richiesta di Sessione
description: Come approvare o rifiutare una richiesta di approvazione di sessione RDP in arrivo in VaultPAM.
persona: operator
category: how-to
last_reviewed: "2026-05-12"
applies_to_versions: ["v1"]
keywords: [approval, session, rdp]
---
# Approvare una Richiesta di Sessione
Quando un utente richiede una sessione RDP che richiede approvazione, ricevete una notifica in VaultPAM. Questo articolo mostra come revisionare e approvare o rifiutare quella richiesta.
## Prima di iniziare
- [ ] Avete il ruolo **Approver** nel Safe rilevante.
- [ ] La richiesta di sessione non è scaduta (TTL predefinito: 10 minuti).
## Approvare la richiesta
1. Aprite **VaultPAM** e cliccate su **Approvazioni** nella barra laterale.
2. Localizzate la richiesta in sospeso e cliccate su **Rivedi**.
3. Controllate i campi **Destinazione**, **Richiedente** e **Giustificazione**.
4. Cliccate su **Approva** o **Rifiuta**.
Il richiedente riceve una notifica in-app immediatamente.
## Risoluzione dei problemi
**Il menu Approvazioni è mancante.**
Non avete il ruolo Approver. Chiedete al vostro admin VaultPAM di aggiungervi come approvatore nel Safe rilevante.
## Articoli correlati
- [Cos'è un Safe?](/concepts/what-is-a-safe)
- [Approvare una sessione in sospeso](/how-to/approve-session)
- [Condividere una registrazione](/how-to/share-recording)
3. Convenzioni per gli screenshot
Gli screenshot aiutano gli operatori a riconoscere il corretto elemento UI a colpo d'occhio. Seguite queste regole per mantenere gli screenshot manutenibili e accessibili.
| Regola | Dettagli |
|---|---|
| Formato | Solo PNG. Non utilizzate JPEG o WebP (gli artefatti di compressione oscurano il testo UI). |
| Larghezza massima | 1024 px. Esportate a densità di pixel 1x (non 2x/Retina) per mantenere la dimensione del file sotto 200 KB. |
| Ritaglio stretto | Mostate solo l'area rilevante. Evitate screenshot a schermo intero se il contesto dell'intero viewport non è necessario. |
| Mascherate dati sensibili | Sfumate o sostituite qualsiasi nome host, indirizzo IP, nome utente o token visibili nello screenshot. Utilizzate una scatola di colore solido, non una sovrapposizione di testo. |
| Testo alternativo | Obbligatorio su ogni immagine. Descrivete cosa mostra lo screenshot, non cosa volete che il lettore faccia. Esempio: Screenshot del pannello Approvazioni che mostra una richiesta in sospeso con un pulsante Approva. |
| Denominazione file | [article-slug]-[step-number]-[short-label].png, es., connect-connector-01-enrollment-token.png. |
| Percorso di archiviazione | Mettete le immagini in docs/help/img/[article-slug]/. |
Markdown per immagini
4. Processo PR
Opzione A — Modifica tramite editor web di GitHub (consigliato per modifiche solo di contenuto)
Ogni articolo pubblicato ha un link Modifica questa pagina in fondo. Cliccandovi si apre l'editor web di GitHub pre-compilato con il file e il branch corretti.
- Cliccate su Modifica questa pagina in fondo all'articolo.
- Apportate le vostre modifiche nell'editor.
- Nel pannello Proponi modifiche, scrivete un breve messaggio di commit (es.,
fix typo in session approval steps). - Cliccate su Proponi modifiche → Crea pull request.
- Nel modulo PR, impostate il titolo per descrivere la modifica (es.,
Fix typo in approve-session article). Nessuna chiave di issue è richiesta per correzioni di puro contenuto. - Sottomettete il PR. Un commento di anteprima viene postato automaticamente con l'URL dev docs con scope PR a
https://dev.euwarden.com/docs/pr-<n>/— il link appare sul PR entro pochi minuti.
Opzione B — Branch da un issue Jira (per lavori strutturati di feature o redesign)
Quando una modifica dell'help center è tracciata sotto un issue Jira (es., aggiunta di un nuovo articolo legato a una release di feature):
- Nome del branch:
AIC-XXXX-help-<slug>(es.,AIC-1234-help-connector-offline-guide). - Prefisso del messaggio di commit:
AIC-XXXX: <description>. - Titolo PR:
[AIC-XXXX] Add connector-offline troubleshooting article.
I PR solo docs (nessuna modifica di codice) possono targetare main direttamente. La chiave di issue Jira è facoltativa per correzioni di typo/phrasing.
Revisione e merge
CODEOWNERS richiede automaticamente la revisione da @OWL-Management/product-analysts e @OWL-Management/pm per tutti i PR che toccano docs/help/**. Un PR deve ricevere almeno un'approvazione prima di poter essere unito.
SLA di revisione: i revisori di contenuto puntano a rispondere entro 2 giorni lavorativi. Se un PR è urgente (es., correzione di un'inesattezza che blocca il supporto), aggiungete l'etichetta help-urgent e taggete il canale Slack #docs.
URL di anteprima
Ogni PR che modifica docs/help/** o docs-site/** attiva una build di anteprima. CI posta l'URL dev docs con scope PR (https://dev.euwarden.com/docs/pr-<n>/) come commento PR fisso entro circa 3 minuti.
Gli ambienti di anteprima non sono indicizzati dai motori di ricerca (il meta tag noindex è impostato).
5. Elenco di controllo prima di sottomettere un PR
- Il frontmatter ha tutti e sei i campi obbligatori:
title,description,persona,category,last_reviewed,applies_to_versions. -
last_reviewedè la data odierna. - Tutti gli screenshot sono PNG, max 1024 px di larghezza, con testo alternativo.
- I dati sensibili negli screenshot sono mascherati.
- I heading seguono l'ordine delle sezioni (nessun H1 all'interno di un blocco di passaggio).
- I link interni utilizzano percorsi relativi al sito (iniziano con
/). - Nessun link rotto (la build Docusaurus avvertirà sui link rotti).
- URL di anteprima controllato e articolo renderizzato correttamente.