Guida di stile per documenti NetApp
Il nostro stile è colloquiale ed empatico, ma siamo sempre professionali e ci mettiamo al punto. Seguire queste linee guida per la scrittura dei contenuti per i documenti NetApp.
Scrivere in maniera conversa
Scrivete come voi quando spiegate qualcosa a un collega professionista. Scrivere in un tono di conversazione ti aiuta a entrare in contatto con il tuo pubblico.
Troppo formale | Troppo casuale | Il nostro stile |
---|---|---|
Se riscontri problemi con il tiering di BlueXP, puoi visualizzare lo stato di salute nella dashboard del cluster per determinare il motivo dell'errore. Lo stato di salute riflette lo stato del sistema ONTAP e di Service Connector. |
Non è divertente quando si verificano errori. Non preoccuparti, consulta la dashboard cluster per scoprire cosa è successo e cosa è interessato. |
In caso di guasto, il tiering di BlueXP visualizza lo stato di integrità "Failed" (guasto) nella dashboard del cluster. Visualizzare lo stato per ottenere informazioni sull'errore. |
Prima di poter eseguire il provisioning dello storage, devi rilevare il cluster ONTAP da BlueXP. Una volta completato il rilevamento, è necessario aprire l'ambiente di lavoro per eseguire il provisioning dello storage. |
Prima di tutto, scopri il cluster ONTAP di BlueXP, quindi apri l'ambiente di lavoro per avviare il provisioning dello storage. Facile! |
Dopo aver scoperto il cluster ONTAP di BlueXP, apri l'ambiente di lavoro per eseguire il provisioning dello storage. |
All'avvio dell'installazione guidata, seguire le istruzioni della procedura guidata per configurare il nodo e unirlo al cluster. La procedura seguente illustra le fasi della procedura guidata. |
Viene visualizzata la procedura guidata di installazione (quasi come una magia), che guida l'utente attraverso il semplice processo di configurazione del nodo e di connessione al cluster. |
Seguire le istruzioni dell'installazione guidata per configurare il nodo e unirlo al cluster. |
È possibile scegliere tra diversi tipi di formati di contenuto per installare e configurare il nuovo sistema. Ogni tipo di formato fornisce istruzioni complete. Scegli il tipo di formato più adatto alle tue esigenze di apprendimento. |
Come si desidera configurare e installare il sistema? Forniamo istruzioni in diversi formati di contenuto, ma solo tu sai come ti piace imparare. |
Scegliere un tipo di formato di contenuto che guidi l'utente nell'installazione e nella configurazione del sistema. |
Usare le contrazioni
Le contrazioni rinforzano un tono di conversazionee molte contrazioni sono facili da capire e tradurre.
Espandi per saperne di più
-
Usare contrazioni come queste, facili da capire e tradurre:
non lo sono
sei tu
non lo è
lo siamo
non lo era
è così
non lo era
andiamo
non lo ha fatto
noi (se è richiesto il futuro)
non è così
non lo farà (se è richiesto un futuro teso)
non farlo
(se è necessario un futuro teso)
-
Non utilizzare contrazioni come queste, difficili da comprendere e tradurre:
sarebbe stato
dovrebbe avere
non lo avremmo mai fatto
non dovrebbe avere
potrebbe essere
non avrei potuto
Scrivete semplicemente
Evitare parole grandi e confuse. Mantieni la semplicità. Stai spiegando qualcosa a un collega professionista, non mostrando il tuo vocabolario.
Piuttosto che questo: "Dissociate l'utente dal vostro account NetApp Cloud Central."
Fai questo: "Rimuovi l'utente dal tuo account NetApp Cloud Central."
Scrivere in maniera minima
Frasi brevi e semplici semplificano la lettura o la scansione dei contenuti. È giusto usare una frase più lunga ogni ora ed allora ma seguirla con una più corta. Così.
Piuttosto che questo: "Per replicare i dati tra un sistema Cloud Volumes ONTAP in AWS e sistemi ONTAP in altre reti, è necessario disporre di una connessione VPN tra Amazon VPC e l'altra rete, ad esempio Azure VNET o la rete aziendale."
Fai questo: "La replica dei dati tra le reti richiede la connessione tramite una VPN. Ad esempio fra Amazon VPC e la rete aziendale o fra AWS e Azure."
Chiediti quanto segue:
-
Gli utenti hanno bisogno di questo contenuto in questa sede, in questo momento?
-
L'interfaccia utente è già abbastanza utile per l'utente? In caso contrario, quale guida aggiuntiva può essere aggiunta brevemente?
-
Posso presentare il contenuto in poche parole senza un suono troppo formale o troppo casuale?
-
Posso abbreviare o semplificare una frase lunga o suddividerla in due o più frasi?
-
Posso utilizzare un elenco per rendere il contenuto più scannable?
-
È possibile utilizzare un grafico per aumentare o sostituire un blocco di testo?
Scrivere attivamente
Evitare la voce passiva è una regola standard per la scrittura tecnica, ma è particolarmente importante utilizzare la voce attiva quando si desidera ascoltare una conversazione.
Voce attiva
Utilizzare la voce attiva in modo che il soggetto della frase esegua l'azione del verbo. Questo significa tipicamente che il verbo segue l'oggetto della frase. La voce attiva continua a scrivere in modo chiaro e nitido. Utilizzare la voce attiva e indirizzare gli utenti direttamente come "utente", a meno che non si disponga di un motivo specifico per utilizzare la voce passiva.
Ecco alcuni esempi di buona scrittura vocale attiva. Scrivi in questo modo:
-
Fornisci le autorizzazioni necessarie prima di implementare il primo cluster.
-
Se il sistema viene spento in modo errato, l'interfaccia visualizza un messaggio di avviso.
-
NetApp ha ricevuto il contratto.
Voce passiva
Nella voce passiva, il doer dell'azione è poco chiaro:
-
Se il sistema non viene spento correttamente, viene visualizzato un messaggio di avviso.
-
NetApp ha ricevuto il contratto.
USA la voce passiva quando:
-
Non si sa chi o cosa ha eseguito l'azione.
-
Si desidera evitare di incolpare gli utenti per i risultati di un'azione.
-
Non è possibile scriverlo, ad esempio per alcune informazioni sui prerequisiti.
Umore imperativo
Utilizzare l'umore imperativo per i passaggi, le direttive, le richieste e le intestazioni per gli elenchi di azioni utente:
-
"Nella pagina ambienti di lavoro, fare clic su rileva e selezionare cluster ONTAP."
-
"Ruotare la maniglia della camma in modo che sia a filo con l'alimentazione."
Prendere in considerazione l'utilizzo della voce imperativa per sostituire la voce passiva:
Piuttosto che questo: "Le autorizzazioni richieste devono essere fornite prima di distribuire il primo cluster."
Fate questo: "Fornite le autorizzazioni necessarie prima di distribuire il vostro primo cluster."
Evitare di utilizzare la voce imperativa per incorporare i passaggi nelle informazioni concettuali e di riferimento.
Per ulteriori convenzioni sui verbi, vedere:
Scrivere contenuti coerenti
"Scrivere come si parla quando si spiega qualcosa a un collega professionista" significa qualcosa di diverso per tutti. Il nostro stile professionale e al contempo conversazionale ci aiuta a metterci in contatto con gli utenti e aumenta la frequenza di incoerenze minori tra più autori contributori:
-
Concentratevi su come rendere i contenuti chiari e facili da utilizzare. Se tutto il contenuto è chiaro e facile da usare, non importa piccole incoerenze.
-
Sia costante all'interno della pagina che state scrivendo.
-
Seguire sempre le linee guida in Scrivere per un pubblico globale.
USA la lingua inclusiva
NetApp ritiene che la documentazione del prodotto non debba contenere un linguaggio esclusivo e discriminatorio. Le parole che utilizziamo possono fare la differenza tra stabilire un rapporto positivo con i nostri clienti o alienarli. Soprattutto con le parole scritte, l'impatto è più importante dell'intento.
Durante la creazione di contenuti per i prodotti NetApp, evitare linguaggi che possano essere interpretati come degradanti, razzisti, sessisti o altrimenti oppressivi. Utilizza invece un linguaggio accessibile e accogliente per tutti coloro che hanno bisogno di utilizzare la documentazione. Ad esempio, invece di "master/slave", utilizzare "primario/secondario".
Utilizzare il linguaggio people-first in cui ci riferiamo prima alla persona, seguito dalla disabilità.
Non usare lui, lui, la sua, lei, lei, o hers in riferimenti generici. Invece:
-
Riscrivere la frase per usare la seconda persona (voi).
-
Riscrivere la frase per avere un sostantivo e un pronome plurali.
-
Utilizzare "la" o "a" invece di un pronome (ad esempio, "il documento").
-
Fare riferimento al ruolo di una persona (ad esempio, lettore, dipendente, cliente o cliente).
-
Utilizzare il termine "persona" o "individuale".
Esempi di parole e frasi considerate inclusive o esclusive
Esempi inclusivi | Esempi esclusivi |
---|---|
Primario/secondario |
Master/slave |
Elenco consentito |
Whitelist |
Elenco bloccato |
Blacklist |
Arrestare |
Uccidere |
Smette di rispondere |
Aspetta |
Fine o Annulla |
Interrompere |
Ora persona |
Ora uomo |
Gli sviluppatori hanno bisogno di accedere ai server nei loro ambienti di sviluppo, ma non hanno bisogno di accedere ai server in Azure. |
Uno sviluppatore ha bisogno di accedere ai server nel suo ambiente di sviluppo, ma non ha bisogno di accedere ai server in Azure. |
Persona cieca |
Non vedenti |
Persona con visione bassa |
Non vedenti |
Arrivare al punto
Ogni pagina dovrebbe iniziare con ciò che è più importante per l'utente. Dobbiamo scoprire cosa sta cercando di fare l'utente e concentrarci sul suo contributo al raggiungimento di tale obiettivo. Per migliorare la capacità di scansione, è inoltre necessario aggiungere parole chiave all'inizio della frase.
Attenersi alle seguenti istruzioni generali:
-
Sii preciso.
-
Evitare le parole di riempimento.
-
Sii breve.
-
Utilizzare il testo formattato o gli elenchi puntati per evidenziare i punti chiave.
Esempi di arrivare al punto
Buoni esempi | Esempi non validi |
---|---|
Se la tua azienda dispone di rigide policy di sicurezza, utilizza la crittografia dei dati in-flight per sincronizzare i dati tra server NFS in reti diverse. |
Cloud Sync può sincronizzare i dati da un server NFS a un altro server NFS utilizzando la crittografia dei dati in-flight. La crittografia dei dati può essere utile se si dispone di rigide politiche di sicurezza per il trasferimento dei dati sulle reti. |
Risparmia tempo creando un modello di documento che include gli stili, i formati e i layout di pagina utilizzati più spesso. Quindi, utilizzare il modello ogni volta che si crea un nuovo documento. |
I modelli forniscono un punto di partenza per la creazione di nuovi documenti. Un modello può includere gli stili, i formati e i layout di pagina utilizzati di frequente. È consigliabile creare un modello se si utilizza spesso lo stesso layout e stile di pagina per i documenti. |
Astra Control offre tre modalità operative che puoi assegnare agli utenti per controllare con attenzione l'accesso tra Astra Control e l'ambiente cloud. |
Astra Control ti consente di assegnare una delle tre modalità operative agli utenti nei tuoi account AWS. Queste modalità ti consentono di controllare con attenzione l'accesso tra Astra Control e il patrimonio cloud in base alle policy IT. |
Utilizza molti elementi visivi
La maggior parte delle persone è un'attività di apprendimento visivo. Utilizza video, diagrammi e screenshot per migliorare l'apprendimento, suddividere i blocchi di testo e fornire un'indicazione visiva agli utenti riguardo a dove si trovano nelle istruzioni dell'attività.
-
Includere una frase che descrive l'immagine seguente: "L'illustrazione seguente mostra i LED dell'alimentazione CA sul pannello posteriore."
-
Fare riferimento alla posizione dell'illustrazione come "seguente" o "precedente", non "sopra" o "sotto".
-
Utilizzare testo alternativo sulla grafica integrata.
-
Se l'immagine è relativa a un passaggio, includere l'immagine subito dopo il passaggio e rientrato per allinearsi con il numero del passaggio.
Best practice sulle schermate:
-
Non includere più di 5 screenshot per attività.
-
Non includere testo in una schermata. Utilizzare invece didascalie numerate.
-
Siate prudenti con gli screenshot che scegliete di includere. Le schermate possono diventare obsolete rapidamente.
Best practice su video o animazioni:
-
I video devono avere una durata inferiore a 5 minuti.
Crea contenuto scannable
Aiuta i lettori a trovare rapidamente i contenuti organizzando il testo sotto le intestazioni di sezione e utilizzando elenchi e tabelle. Intestazioni, frasi e paragrafi dovrebbero essere brevi e facili da leggere. Le informazioni più importanti devono essere fornite per prime.
Creare flussi di lavoro che aiutino gli utenti a raggiungere gli obiettivi prefissati
Gli utenti leggono i nostri contenuti per raggiungere un obiettivo specifico. Gli utenti vogliono trovare i contenuti di cui hanno bisogno, raggiungere i propri obiettivi e tornare a casa con le loro famiglie. Il nostro compito non è quello di documentare prodotti o funzioni. Il nostro compito è documentare gli obiettivi degli utenti. I flussi di lavoro sono il modo più diretto per aiutare gli utenti a raggiungere i propri obiettivi.
Un flusso di lavoro è una serie di passaggi o sottoattività che descrivono come raggiungere un obiettivo dell'utente. L'ambito di un workflow è un obiettivo completo.
Ad esempio, la procedura per creare un volume non sarebbe un workflow, perché la creazione di un volume in sé non è un obiettivo completo. La procedura per rendere lo storage disponibile per un server ESX potrebbe essere un workflow. I passaggi includono non solo la creazione di un volume, ma anche l'esportazione del volume, l'impostazione delle autorizzazioni necessarie, la creazione di un'interfaccia di rete e così via.
I flussi di lavoro derivano dai casi di utilizzo dei clienti. Un flusso di lavoro mostra solo l'unico modo migliore per raggiungere l'obiettivo.
Organizzare i contenuti in base all'obiettivo dell'utente
Aiutare gli utenti a trovare rapidamente le informazioni organizzando i contenuti in base all'obiettivo che l'utente sta cercando di raggiungere. Questo standard si applica al sommario (navigazione) di un sito di documentazione, nonché alle singole pagine che appaiono sul sito.
Organizzare il contenuto come segue:
- La prima voce nella navigazione a sinistra (livello alto)
-
Organizzare il contenuto intorno agli obiettivi che l'utente sta cercando di raggiungere. Ad esempio, la prima voce nella navigazione del sito potrebbe essere "Get Started" (inizia) o "Protect data" (Proteggi dati).
- Le voci di secondo livello nella navigazione per il sito della documentazione (livello medio)
-
Organizza i contenuti in base alle attività più ampie che compongono gli obiettivi.
Ad esempio, la sezione "per iniziare" potrebbe includere le seguenti pagine:
-
Preparazione per l'installazione
-
Installare e configurare <product name>
-
Impostare la licenza
-
Cosa fare in seguito
-
- Singole pagine (livello dettagliato)
-
In ogni pagina, organizzare il contenuto intorno alle singole attività che compongono le attività più ampie. Ad esempio, i contenuti che gli utenti devono preparare per l'installazione o per configurare il disaster recovery.
Una pagina può descrivere una singola attività o più attività. Se sono presenti più attività, è necessario descriverle in sezioni separate della pagina. Ogni sezione dovrebbe concentrarsi su un singolo aspetto di apprendimento o di esecuzione dell'attività più ampia. Ciò potrebbe includere alcune informazioni concettuali e basate sui riferimenti necessarie per completare l'attività.
Scrivere per un pubblico globale
La nostra documentazione è letta da molti utenti la cui lingua principale non è l'inglese. Traduciamo i nostri contenuti in altre lingue utilizzando gli strumenti di traduzione automatica neurale o la traduzione umana. Per supportare il nostro pubblico globale, scriviamo contenuti facili da leggere e da tradurre.
Segui queste linee guida per scrivere per un pubblico globale:
-
Scrivere frasi brevi e semplici.
-
Utilizzare la grammatica e la punteggiatura standard.
-
Utilizzare una parola per un significato e un significato per una parola.
-
Utilizzare contrazioni comuni.
-
USA la grafica per chiarire o sostituire il testo.
-
Evitare di incorporare testo nella grafica.
-
Evitare di avere tre o più sostantivi in una stringa.
-
Evitare antecedenti poco chiari.
-
Evita gergo, colloquialismi e metafore.
-
Evitare esempi non tecnici.
-
Evitare di utilizzare ritorni a capo rigidi e spaziatura.
-
Non usare umorismo o ironia.
-
Non utilizzare contenuti discriminatori.
-
Non usi il linguaggio di genere-polarizzato a meno che stiate scrivendo per una persona specifica.
Linee guida dalla a alla Z
acronimi e abbreviazioni
Utilizzare acronimi e abbreviazioni ben noti per la familiarità, ma evitare quelli oscuri che potrebbero influenzare negativamente la chiarezza e la reperibilità. Per ulteriori convenzioni relative a acronimi e abbreviazioni, vedere la "Microsoft Writing Style Guide".
voce attiva (rispetto a voce passiva)
Fare riferimento a. Scrivere attivamente.
ammonizioni
Le ammonizioni sono uno strumento potente quando usato correttamente. Possono attirare l'attenzione su informazioni importanti, fornire suggerimenti utili o avvisare gli utenti di potenziali pericoli. Se utilizzati in modo eccessivo, perdono il loro impatto e possono causare l'affaticamento dell'utente. Ecco alcune linee guida per garantire l'uso efficace delle ammonizioni.
Utilizzare le seguenti etichette per separare le ammonizioni dal flusso di contenuti principale:
-
NOTA utilizzare la NOTA per evidenziare informazioni importanti che devono distinguersi dal resto del testo. Tuttavia, evitare di utilizzare UNA NOTA per le informazioni "utili da conoscere" che non sono essenziali per gli utenti per capire o completare un'attività. Lo scopo di una NOTA è di attirare l'attenzione del lettore su punti critici che potrebbero altrimenti trascurare.
-
I suggerimenti dovrebbero essere utilizzati con parsimonia, se non del tutto, poiché la nostra politica è quella di documentare le informazioni sulle Best practice per impostazione predefinita. Se necessario, utilizzare il SUGGERIMENTO per evidenziare le informazioni sulle procedure consigliate che consentono agli utenti di utilizzare un prodotto o completare un passaggio o un'attività in modo più semplice ed efficiente. Un SUGGERIMENTO dovrebbe fornire consigli utili o scorciatoie che possano migliorare l'esperienza dell'utente.
-
ATTENZIONE prestare attenzione per avvisare gli utenti in merito a condizioni o azioni che possono portare a risultati indesiderati, incluse lesioni personali o danni alle apparecchiature. PRESTARE ATTENZIONE per attirare l'attenzione sui potenziali pericoli che l'utente deve evitare per prevenire danni o interruzioni.
-
Utilizzare solo gli ammonimenti supportati. Qualsiasi altro tipo di formattazione non è supportato.
-
Evitare di utilizzare eccessivamente gli ammonimenti. L'uso eccessivo può portare gli utenti a ignorare queste importanti sezioni perché le considerano il "cassetto spazzatura" dei nostri documenti.
-
Come regola generale, limitare il numero di ammonizioni a un massimo di 3 per pagina.
-
Fornire informazioni chiare e concise all'interno dell'ammonizione. Il messaggio deve essere breve e preciso, consentendo agli utenti di comprendere rapidamente l'importanza delle informazioni fornite.
-
Evitare gli ammonimenti di AsciDoc in una tavola. Se il contenuto deve essere identificato come nota, suggerimento o attenzione, utilizzare Nota:, Suggerimento:, o attenzione: come collegamento in linea al testo.
dopo (rispetto a "una volta")
-
Utilizzare "dopo" per indicare una cronologia: "Accendere il computer dopo averlo collegato."
-
Utilizzare "una volta" solo per indicare "una volta".
inoltre
-
Utilizzare "also" per indicare "in aggiunta".
-
Non utilizzare "anche" per indicare "in alternativa".
e/o.
Scegliere il termine più preciso, se disponibile. Se nessuno dei due termini è più preciso dell'altro, utilizzare "e/o".
come
Non utilizzare "come" per indicare "perché".
utilizzando (anziché "utilizzando" o "con")
-
Utilizzare "usando" quando l'entità che sta facendo l'uso è l'oggetto: "È possibile aggiungere nuovi componenti al repository utilizzando il menu componenti."
-
È possibile iniziare una frase "utilizzando" o "con", che a volte sono accettabili con i nomi dei prodotti: "Utilizzando SnapDrive, è possibile gestire dischi virtuali e copie Snapshot in un ambiente Windows."
can (rispetto a "potrebbe", "maggio", "dovrebbe" o "deve")
-
Utilizzare "CAN" per indicare la capacità: "È possibile confermare le modifiche in qualsiasi momento durante questa procedura."
-
Utilizzare "potrebbe" per indicare la possibilità: "Il download di più programmi potrebbe influire sul tempo di elaborazione."
-
Non utilizzare "può", che è ambiguo perché potrebbe significare capacità o permesso.
-
Utilizzare "dovrebbe" per indicare un'azione consigliata ma facoltativa. Si consiglia di utilizzare una frase alternativa, ad esempio "si consiglia".
-
Evitare di utilizzare "must" perché è passivo. Considerare la possibilità di riaffermare il pensiero come un'istruzione utilizzando la voce imperativa. Se si utilizza "must", utilizzarlo per indicare un'azione o una condizione richiesta.
capitalizzazione
USA la maiuscola in stile frase (minuscolo) per quasi tutto. Solo maiuscolo:
-
La prima parola di frasi e intestazioni, comprese le intestazioni delle tabelle
-
La prima parola degli elementi dell'elenco, inclusi i frammenti di frase
-
Sostantivi appropriati
-
Titoli e sottotitoli DOC (maiuscoli e preposizioni di cinque o più lettere)
-
Elementi dell'interfaccia utente, ma solo se sono maiuscoli nell'interfaccia. In caso contrario, utilizzare caratteri minuscoli.
avvisi di attenzione
Fare riferimento a. ammonizioni.
contrazioni
Utilizzare contrazioni come parte della scrittura conversazionale.
verifica (anziché "conferma" o "verifica")
-
Utilizzare "assicurarsi" per indicare "assicurarsi". Includere "che", come appropriato: "Assicurarsi che vi sia sufficiente spazio bianco intorno alle illustrazioni."
-
Non utilizzare mai "garantire" per implicare una promessa o una garanzia: "Utilizzare Cloud Manager per garantire il provisioning di volumi NFS e CIFS su cluster ONTAP."
-
Utilizzare "confirm" o "verify" quando si intende che l'utente dovrebbe controllare due volte qualcosa che già esiste o che è già accaduto: "Verificare che NFS sia configurato sul cluster."
grafica
Fare riferimento a. Utilizza molti elementi visivi.
grammatica
Se non diversamente specificato, seguire le convenzioni di grammatica, punteggiatura e ortografia descritte in:
in caso contrario
Non utilizzare "se non" da solo per fare riferimento alla frase precedente:
-
Piuttosto che questo: "Il calcolatore dovrebbe essere spento. In caso contrario, disattivalo."
-
Eseguire questa operazione: "Verificare che il computer sia spento."
se (rispetto a "se" o "quando")
-
Utilizzare "if" per indicare una condizione, ad esempio nelle costruzioni "if this, then that".
-
Utilizzare "se" in presenza di una condizione dichiarata o implicita "o meno". Per semplificare la traduzione, spesso è meglio sostituire "se" o meno con "se" da solo.
-
Utilizzare "quando" per indicare un intervallo di tempo.
voce imperativa
Fare riferimento a. Scrivere attivamente.
funzionalità o release future
Non fare riferimento ai tempi o al contenuto delle prossime versioni o funzionalità dei prodotti, se non dire che una funzione o funzione non è "attualmente supportata".
Articoli della Knowledge base: Fare riferimento a.
Se necessario, consultare gli articoli della Knowledge base di NetApp nei contenuti. Per le pagine delle risorse e il contenuto di GitHub, inserire il link nel testo in esecuzione.
elenchi
Gli elenchi di informazioni sono generalmente più facili da acquisire e assorbire rispetto ai blocchi di testo. Prendi in considerazione i modi per semplificare le informazioni complesse presentarle sotto forma di elenco. Ecco alcune linee guida generali, ma utilizza il tuo giudizio:
-
Assicurarsi che il motivo dell'elenco sia chiaro. Introdurre l'elenco con una frase completa, un frammento di frase con due punti o un'intestazione.
-
Quando si utilizza un elenco all'interno di un elenco, limitare la struttura al massimo a due livelli di profondità per mantenere chiarezza e leggibilità. Se si ha bisogno di più livelli, è consigliabile riorganizzare il contenuto per semplificare la navigazione e la comprensione da parte degli utenti.
-
Tutti gli elenchi, compresi quelli nidificati, devono contenere da due a sette voci. In generale, più brevi sono le informazioni di ciascuna voce, più voci è possibile aggiungere mantenendo la scansione dell'elenco. Se un elenco contiene più voci che contengono elenchi nidificati, prendere in considerazione l'utilizzo di sezioni o titoli di blocco per dividere l'intero elemento in frammenti più consumabili.
-
Le voci dell'elenco devono essere il più possibile scannable. Evitare blocchi di testo che impedano la scansione delle voci dell'elenco.
-
Le voci dell'elenco devono iniziare con una lettera maiuscola e le voci dell'elenco devono essere grammaticamente parallele. Ad esempio, iniziare ogni voce con un nome o un verbo:
-
Se tutte le voci dell'elenco sono frasi complete, terminarle con punti.
-
Se tutte le voci dell'elenco sono frammenti di frase, non terminarle con punti.
-
-
Le voci dell'elenco devono essere ordinate in modo logico, ad esempio in ordine alfabetico o cronologico.
localizzazione
Fare riferimento a. Scrivere per un pubblico globale.
minimalismo
Fare riferimento a. Scrivere in maniera minima.
numeri
-
Utilizzare numeri arabi per 10 e tutti i numeri superiori a 10, con le seguenti eccezioni:
-
Se si inizia una frase con un numero, utilizzare una parola, non un numero arabo.
-
Utilizzare le parole (non i numeri) per i numeri approssimativi.
-
-
Utilizzare parole per numeri inferiori a 10.
-
Se una frase contiene una combinazione di numeri inferiori a 10 e superiori a 10, utilizzare i numeri arabi per tutti i numeri.
-
Per ulteriori convenzioni numeriche, vedere "Microsoft Writing Style Guide".
plagio
Documentiamo i prodotti NetApp e l'interazione dei prodotti NetApp con prodotti di terze parti. Non documentiamo prodotti di terze parti. Non dovremmo mai copiare e incollare contenuti di terze parti nei nostri documenti e non dovremmo mai farlo.
prerequisiti
I prerequisiti identificano le condizioni che devono esistere o le azioni che gli utenti devono completare prima di avviare l'attività corrente.
-
Identificare la natura del contenuto con un'intestazione, ad esempio "Prerequisiti", "prima di iniziare" o "prima di iniziare".
-
Utilizzare la voce passiva per la formulazione dei prerequisiti, se è opportuno:
-
"NFS o CIFS devono essere configurati nel cluster."
-
"Per aggiungere il cluster a Cloud Manager, è necessario disporre dell'indirizzo IP di gestione cluster e della password per l'account utente amministratore."
-
-
Chiarire il prerequisito secondo necessità: "NFS o CIFS devono essere configurati nel cluster. Puoi configurare NFS e CIFS usando System Manager o la CLI."
-
Considerare altri modi per presentare le informazioni, ad esempio se sarebbe opportuno modificare il contenuto come primo passo dell'attività corrente:
-
Prerequisito: "È necessario disporre delle autorizzazioni necessarie prima di distribuire il primo cluster."
-
Passaggio: "Fornire le autorizzazioni necessarie per implementare il primo cluster."
-
precedente (rispetto a "prima", "precedente" o "precedente")
-
Se possibile, sostituire "precedente" con "precedente".
-
Se non è possibile utilizzare "prima", utilizzare "precedente" come aggettivo per fare riferimento a qualcosa che si è verificato prima nel tempo o con un ordine di importanza superiore.
-
Utilizzare "Previous" (precedente) per indicare qualcosa che si è verificato in precedenza a un orario non specificato.
-
Utilizzare "precedente" per indicare qualcosa che si è verificato immediatamente in precedenza.
punteggiatura
Mantieni la semplicità. In generale, maggiore è la punteggiatura inclusa in una frase, maggiore è il numero di cellule cerebrali necessarie per comprenderle.
-
Utilizzare una virgola seriale (virgola Oxford) prima della congiunzione ("e" o "o") in un elenco narrativo di tre o più elementi.
-
Limitare l'uso di punti e virgola e punti e virgola.
-
Se non diversamente specificato, seguire le convenzioni di grammatica, punteggiatura e ortografia descritte in:
da
Utilizzare "da" per indicare un intervallo di tempo. Non utilizzare "da" per indicare "perché".
ortografia
Se non diversamente specificato, seguire le convenzioni di grammatica, punteggiatura e ortografia descritte in:
quello (contro "quale" o "chi")
-
Utilizzare "that" (senza virgola finale) per introdurre clausole necessarie affinché la frase abbia senso.
-
Utilizzare "questo" anche se la frase è chiara in inglese senza di essa: "Verificare che il computer sia spento."
-
Utilizzare "which" (con una virgola finale) per introdurre clausole che aggiungono informazioni di supporto, ma non sono necessarie perché la frase abbia senso.
-
Utilizzare "WHO" per introdurre clausole relative alle persone.
marchi
Nella maggior parte dei nostri contenuti tecnici non sono inclusi i simboli dei marchi perché le dichiarazioni legali nei nostri modelli sono sufficienti. Tuttavia, durante l'utilizzo, seguiamo tutte le regole di utilizzo "Termini con marchio NetApp":
-
Utilizzare i termini con marchio (con o senza il simbolo) solo come aggettivi, mai come sostantivi, verbi o verbali.
-
Non abbreviare, sillabare o utilizzare il corsivo per i termini registrati.
-
Non pluralizzare i termini del marchio. Se è richiesta una forma plurale, utilizzare il nome del marchio come aggettivo che modifica un sostantivo plurale.
-
Non utilizzare una forma possessiva di un termine con marchio. È possibile utilizzare la forma possessiva dei nomi delle società, come NetApp, quando i nomi vengono utilizzati in senso generale, piuttosto che come termini con marchio.
interfaccia utente
Quando si documenta un'interfaccia utente, fare affidamento sull'interfaccia il più possibile per guidare l'utente.
Utilizzare uno stile semplice e mimale quando si documentano le interfacce utente.
Details
-
Si supponga che l'utente stia utilizzando l'interfaccia durante la lettura del contenuto:
-
Non guidare l'utente attraverso una procedura guidata o una schermata passo dopo passo. Indicate solo cose importanti che non sono evidenti dall'interfaccia.
-
Non includere "fare clic su OK" o "fare clic su Salva" o "il volume è stato creato" o qualsiasi altra cosa ovvia a qualcuno che esegue l'attività.
-
Presupporre il successo. A meno che non si preveda un'operazione che non abbia esito positivo per la maggior parte del tempo, non documentare il percorso di errore. Si supponga che l'interfaccia fornisca una guida adeguata.
-
-
Non utilizzare affatto il "clic". Utilizzare sempre "SELECT" perché questa parola copre mouse, touch, tastiera e qualsiasi altro modo di fare una scelta.
-
Concentrate i contenuti su un flusso di lavoro che si adatta a un caso di utilizzo del cliente e su come portare l'utente nel posto giusto nell'interfaccia per avviare il flusso di lavoro.
-
Documentare sempre l'unico modo migliore per raggiungere l'obiettivo dell'utente.
-
Se il flusso di lavoro richiede una decisione significativa, assicurarsi di documentare una regola decisionale.
-
Utilizzare il numero minimo di passaggi necessari per la maggior parte degli utenti.
Evitare di documentare il livello di granularità che richiede la denominazione degli elementi dell'interfaccia utente.
Details
Affidati all'interfaccia per guidare l'utente attraverso le specifiche dell'interazione. Se è necessario ottenere questo specifico, assegnare un nome all'etichetta sull'elemento. Ad esempio, "selezionare il volume desiderato" o "selezionare "Usa volume esistente"." Non è necessario assegnare un nome a menu, pulsanti di opzione o caselle di controllo, ma è sufficiente utilizzare l'etichetta.
Per le icone che gli utenti devono selezionare, utilizzare un'immagine dell'icona. Non cercare di denominarlo. Questa regola si applica alle icone come freccia, matita, ingranaggio, kabob, hamburger, e così via.
Seguire l'ortografia e le maiuscole utilizzate dall'interfaccia utente per identificare le etichette.
Details
Se un'etichetta è seguita da ellissi, non includere i ellissi quando si assegna un nome all'oggetto. Incoraggiare gli sviluppatori a utilizzare le maiuscole in stile titolo per le etichette dell'interfaccia utente, in modo da semplificarne la scrittura.
Utilizzare le schermate con parsimonia.
Details
Una schermata occasionale ("screenshot") aiuta gli utenti a essere sicuri di trovarsi nella posizione giusta in un'interfaccia quando avviano o cambiano le interfacce durante un flusso di lavoro. Non utilizzare le schermate acquisite per visualizzare i dati da inserire o il valore da selezionare.
mentre (rispetto a "anche se")
-
Utilizzare "While" per indicare un evento che si verifica nel tempo.
-
Utilizzare "anche se" per rappresentare un'attività che si verifica quasi contemporaneamente o poco dopo un'altra attività.