Skip to main content
Contributor's Guide
Die deutsche Sprachversion wurde als Serviceleistung für Sie durch maschinelle Übersetzung erstellt. Bei eventuellen Unstimmigkeiten hat die englische Sprachversion Vorrang.

Style Guide für NetApp Dokumentationen

Beitragende
PDFs

Unser Stil ist umgangssprachlich und einfühlsam, aber wir bleiben professionell und kommen zum Punkt. Folgen Sie beim Schreiben der Inhalte für NetApp Dokumentationen diesen Richtlinien.

Konvergieren

Schreiben Sie, wie Sie sprechen, wenn Sie einem professionellen Kollegen etwas erklären. Schreiben in einem Gesprächston hilft Ihnen, mit Ihrem Publikum zu verbinden.

Zu formell Zu lässig Unser Stil

Wenn Probleme mit BlueXP Tiering auftreten, können Sie im Cluster Dashboard den Integritätsstatus anzeigen und ermitteln, warum der Fehler aufgetreten ist. Der Systemzustand gibt den Status des ONTAP-Systems und des Servicesteckers wieder.

Es macht keinen Spaß, wenn Ausfälle auftreten. Machen Sie sich keine Sorgen, schauen Sie sich einfach das Cluster Dashboard an, um zu sehen, was passiert ist und was davon betroffen ist.

Wenn ein Fehler auftritt, zeigt BlueXP Tiering im Cluster Dashboard den Integritätsstatus „Fehlgeschlagen“ an. Zeigen Sie den Status an, um Informationen über den Fehler zu erhalten.

Bevor Sie Storage bereitstellen können, müssen Sie Ihr ONTAP-Cluster aus BlueXP erkennen. Nach Abschluss der Bestandsaufnahme müssen Sie die Arbeitsumgebung öffnen, um Storage bereitzustellen.

Zunächst müssen Sie nur Ihr ONTAP Cluster aus BlueXP erkennen und dann die Arbeitsumgebung öffnen, um mit der Storage-Bereitstellung zu beginnen. Ganz Einfach!

Nachdem Sie das ONTAP Cluster aus BlueXP erkannt haben, öffnen Sie die Arbeitsumgebung für die Bereitstellung von Storage.

Befolgen Sie beim Starten des Setup-Assistenten die Anweisungen im Assistenten, um den Node einzurichten und dem Cluster beizutreten. Die folgenden Schritte führen Sie durch die Schritte im Assistenten.

Der Setup-Assistent wird angezeigt (fast wie Magic), um Sie durch den einfachen Prozess der Einrichtung des Node und der Verbindung mit dem Cluster zu führen.

Befolgen Sie die Anweisungen im Setup-Assistenten, um den Node einzurichten und dem Cluster beizutreten.

Sie können zwischen verschiedenen Inhaltstypen wählen, um Ihr neues System zu installieren und einzurichten. Jeder Formattyp enthält vollständige Anweisungen. Wählen Sie den Formattyp aus, der am ehesten der Art entspricht, die Sie lernen möchten.

Wie möchten Sie Ihr System einrichten und installieren? Wir stellen Anweisungen in verschiedenen Inhaltstypen zur Verfügung, aber nur Sie wissen, wie Sie lernen möchten.

Wählen Sie einen Inhaltstyp aus, der Sie bei der Installation und Einrichtung des Systems unterstützt.

Verwenden Sie Kontraktionen

Kontraktionen verstärken A Gesprächston, Und viele Kontraktionen sind leicht zu verstehen und zu übersetzen.

Erweitern, um mehr zu erfahren

  • Verwenden Sie Kontraktionen wie diese, die leicht zu verstehen und zu übersetzen sind:

    Das sind sie nicht

    Du schon

    Ist nicht

    Wir sind

    War nicht

    Es ist

    Waren Sie nicht

    Lass uns

    Nicht

    Wir werden (wenn die Zukunft angespannt ist)

    Das nicht

    Wird nicht (wenn eine zukünftige Spannung erforderlich ist)

    Nicht

    Sie werden (wenn eine ZukunftspInfrastruktur erforderlich ist)

  • Verwenden Sie keine Kontraktionen wie diese, die schwer zu verstehen und zu übersetzen sind:

    Das wäre schon

    Sollte ich

    Das wäre nicht der Fall

    Das sollte nicht sein

    Das könnte ich Ihnen sagen

    Hätte nicht sein können

Schreiben Sie einfach

Vermeiden Sie große und verwirrende Worte. Einfach Sie erklären einem professionellen Kollegen etwas, ohne Ihr Vokabular zu zeigen.

Anstatt dies: "Distanzieren Sie den Benutzer von Ihrem NetApp Cloud Central-Konto."

Do this: "Entfernen Sie den Benutzer aus Ihrem NetApp Cloud Central-Konto."

Minimale Schreibvorgänge

Kurze, einfache Sätze erleichtern das Lesen oder Scannen von Inhalten. Es ist in Ordnung, ab und zu einen längeren Satz zu verwenden, aber folgen Sie ihm mit einem kürzeren. So.

Anstatt dies: "Um Daten zwischen einem Cloud Volumes ONTAP-System in AWS und ONTAP-Systemen in anderen Netzwerken zu replizieren, müssen Sie über eine VPN-Verbindung zwischen der Amazon VPC und dem anderen Netzwerk verfügen, zum Beispiel einem Azure vnet oder Ihrem Firmennetzwerk."

Do this: "Die Datenreplikation zwischen Netzwerken erfordert eine Verbindung über ein VPN. Beispielsweise zwischen Ihrer Amazon VPC und Ihrem Unternehmensnetzwerk oder zwischen AWS und Azure.“

Stellen Sie sich folgende Fragen:

  • Benötigen die Benutzer diese Inhalte zur Zeit an diesem Ort?

  • Führt die Benutzeroberfläche den Anwender bereits gut genug? Falls nicht, welche zusätzliche Anleitung kann kurz und bündig hinzugefügt werden?

  • Kann ich den Inhalt in weniger Worten darstellen, ohne zu formell oder zu lässig zu klingen?

  • Kann ich einen langen Satz verkürzen oder vereinfachen oder in zwei oder mehr Sätze unterteilen?

  • Kann ich eine Liste verwenden, um den Inhalt scannbarer zu machen?

  • Kann ich eine Grafik verwenden, um einen Textblock zu erweitern oder zu ersetzen?

Aktiv schreiben

Die Vermeidung passiver Stimme ist eine Standardregel für das technische Schreiben, aber es ist besonders wichtig, aktive Stimme zu verwenden, wenn Sie konversationell klingen möchten.

Aktive Stimme

Verwenden Sie aktive Stimme, damit der Gegenstand des Satzes die Aktion des Verbs ausführt. Dies bedeutet in der Regel, dass das Verb dem Thema des Satzes folgt. Aktive Stimme hält das Schreiben scharf und klar. Verwenden Sie aktive Stimme und sprechen Sie Benutzer direkt als „Sie“ an, es sei denn, Sie haben einen bestimmten Grund, passive Stimme zu verwenden.

Hier sind einige Beispiele für gute aktive Stimme schreiben. So schreiben:

  • Geben Sie die erforderlichen Berechtigungen an, bevor Sie das erste Cluster bereitstellen.

  • Wenn Sie das System nicht ordnungsgemäß herunterfahren, zeigt die Schnittstelle eine Warnmeldung an.

  • NetApp hat den Vertrag erhalten.

Passive Stimme

In passiver Stimme ist der Täter der Aktion unklar:

  • Wenn das System nicht ordnungsgemäß heruntergefahren wird, wird eine Warnmeldung angezeigt.

  • NetApp erhielt den Auftrag.

Passive Stimme verwenden, wenn:

  • Sie wissen nicht, wer oder was die Aktion durchgeführt hat.

  • Sie möchten vermeiden, den Benutzern die Schuld für die Ergebnisse einer Aktion zu geben.

  • Sie können sich nicht umschreiben, z. B. für einige Informationen zu den Voraussetzungen.

Grundstimmung

Verwenden Sie die Grundstimmung für Schritte, Anweisungen, Anforderungen und Überschriften für Listen von Benutzeraktionen:

  • „Klicken Sie auf der Seite Arbeitsumgebungen auf ermitteln, und wählen Sie ONTAP-Cluster aus.“

  • „Drehen Sie den Nockengriff so, dass er bündig an der Stromversorgung anliegt.“

Ziehen Sie in Betracht, die passive Stimme durch eine zwingende Stimme zu ersetzen:

Anstatt dies: "Die erforderlichen Berechtigungen müssen vor der Bereitstellung des ersten Clusters gegeben werden."

Do this: "Geben Sie die erforderlichen Berechtigungen, bevor Sie Ihren ersten Cluster bereitstellen."

Vermeiden Sie die Verwendung von Imperativ Voice, um Schritte in konzeptionelle und Referenzinformationen einzubetten.

Weitere Verbkonventionen finden Sie unter:

Schreiben Sie konsistente Inhalte

„Schreiben Sie, wie Sie sprechen, wenn Sie einem professionellen Kollegen etwas erklären“ bedeutet für jeden etwas anderes. Unser professioneller, aber konversationeller Stil hilft uns, uns mit Benutzern in Verbindung zu bringen und erhöht die Häufigkeit kleinerer Inkonsistenzen zwischen mehreren Autoren:

  • Konzentrieren Sie sich darauf, den Inhalt klar und einfach zu gestalten. Wenn der gesamte Inhalt klar und einfach zu bedienen ist, sind kleinere Unstimmigkeiten nicht von Bedeutung.

  • Seien Sie innerhalb der Seite, die Sie schreiben, konsistent.

  • Befolgen Sie immer die Richtlinien unter Schreiben Sie für ein globales Publikum.

Verwenden Sie eine inklusiv Sprache

NetApp ist der Ansicht, dass die Produktdokumentation nicht diskriminierende, exklusive Inhalte enthalten sollte. Die Worte, die wir benutzen, können einen Unterschied machen zwischen einer positiven Beziehung zu unseren Kunden oder ihrer Entfremdung. Vor allem bei geschriebenen Worten ist die Wirkung wichtiger als die Absicht.

Beim Erstellen von Inhalten für NetApp Produkte vermeiden Sie eine Sprache, die als entniedrigend, rassistisch, sexistisch oder anderweitig bedrückend interpretiert werden kann. Verwenden Sie stattdessen Sprache, die allen zugänglich ist und die die Dokumentation verwenden müssen. Verwenden Sie zum Beispiel anstelle von „Master/Slave“ „Primary/Secondary“.

Verwenden Sie die Menschen-erste Sprache, in der wir zuerst auf die Person, gefolgt von der Behinderung beziehen.

Benutzt nicht er, ihn, seine, sie, sie, sie, oder in allgemeinen Referenzen. Stattdessen:

  • Schreiben Sie den Satz um, um die zweite Person (Sie) zu verwenden.

  • Schreiben Sie den Satz neu, um ein PluralSubstantiv und Pronomen zu haben.

  • Verwenden Sie anstelle eines Pronomen „das“ oder „A“ (z. B. „das Dokument“).

  • Beziehen Sie sich auf die Rolle einer Person (z. B. Leser, Mitarbeiter, Kunde oder Kunde).

  • Verwenden Sie den Begriff „Person“ oder „Einzelperson“.

Beispiele für Wörter und Sätze, die als inklusiv oder exklusiv gelten

Inklusive Beispiele Exklusive Beispiele

Primär/sekundär

Master/Slave

Liste zulässig

Whitelist

Blockierte Liste

Schwarze Liste

Hör Auf

Töten

Reagiert nicht mehr

Bitte Bleiben Sie Dran

Ende oder Abbrechen

Abbrechen

Personstunde

Arbeitsstunde

Entwickler benötigen Zugriff auf die Server in ihrer Entwicklungsumgebung, benötigen aber keinen Zugriff auf die Server in Azure.

Ein Entwickler benötigt Zugriff auf die Server in seiner Entwicklungsumgebung, benötigt aber keinen Zugriff auf die Server in Azure.

Person, die blind ist

Sehbeeinträchtigung

Person mit niedrigem Sehvermögen

Sehbeeinträchtigung

Kommen Sie zum Punkt

Jede Seite sollte mit dem beginnen, was für den Benutzer am wichtigsten ist. Wir müssen herausfinden, was der Benutzer zu tun versucht, und uns darauf konzentrieren, ihm dabei zu helfen, dieses Ziel zu erreichen. Wir sollten auch Schlüsselwörter am Anfang des Satzes hinzufügen, um die Scanfähigkeit zu verbessern.

Befolgen Sie die folgenden allgemeinen Satzrichtlinien:

  • Seien Sie präzise.

  • Vermeiden Sie Füllwörter.

  • Sei kurz.

  • Verwenden Sie formatierten Text oder Aufzählungslisten, um wichtige Punkte hervorzuheben.

Beispiele für den Weg zum Punkt

Gute Beispiele Schlechte Beispiele

Wenn Ihr Unternehmen über strenge Sicherheitsrichtlinien verfügt, verwenden Sie die Verschlüsselung von Daten während der Übertragung, um Daten zwischen NFS-Servern in unterschiedlichen Netzwerken zu synchronisieren.

Cloud Sync kann Daten mithilfe der Verschlüsselung der aktiven Daten von einem NFS-Server auf einen anderen NFS-Server synchronisieren. Die Verschlüsselung der Daten kann bei strengen Sicherheitsrichtlinien für die Übertragung von Daten über Netzwerke hilfreich sein.

Sparen Sie Zeit, indem Sie eine Dokumentvorlage erstellen, die die Formate, Formate und Seitenlayouts enthält, die Sie am häufigsten verwenden. Verwenden Sie dann die Vorlage, wenn Sie ein neues Dokument erstellen.

Vorlagen bieten einen Ausgangspunkt für die Erstellung neuer Dokumente. Eine Vorlage kann die Formate, Formate und Seitenlayouts enthalten, die Sie häufig verwenden. Wenn Sie häufig dasselbe Seitenlayout und dieselbe Formatvorlage für Dokumente verwenden, sollten Sie eine Vorlage erstellen.

Astra Control bietet drei Betriebsmodi, die Ihren Benutzern zugewiesen werden können, um den Zugriff zwischen Astra Control und Ihrer Cloud-Umgebung sorgfältig zu kontrollieren.

Astra Control ermöglicht es Ihnen, einen von drei Betriebsmodi für Benutzer in Ihren AWS Konten zuzuweisen. Sie können den Zugriff zwischen Astra Control und Ihrem Cloud-Bestand anhand Ihrer IT-Richtlinien sorgfältig steuern.

Verwenden Sie viele Visuals

Die meisten Menschen sind visuelle Lernende. Verwenden Sie Videos, Diagramme und Screenshots, um das Lernen zu verbessern, Textblöcke aufzubrechen und Benutzern einen visuellen Hinweis darauf zu geben, wo sie sich in den Aufgabenanweisungen befinden.

  • Fügen Sie einen Einleitungssatz ein, der das folgende Bild beschreibt: „Die folgende Abbildung zeigt die NetzteilLEDs auf der Rückseite.“

  • Beziehen Sie sich auf die Position der Abbildung als „folgt“ oder „vorausgehend“, nicht „oben“ oder „unten“.

  • Verwenden Sie alt-Text auf integrierten Grafikfunktionen.

  • Wenn das visuelle einen Schritt betrifft, fügen Sie das visuelle direkt nach dem Schritt ein und eingerückt, um es an der Schrittnummer auszurichten.

Best Practices auf Screenshots:

  • Fügen Sie nicht mehr als 5 Screenshots pro Aufgabe ein.

  • Fügen Sie keinen Text in einen Screenshot ein. Verwenden Sie stattdessen nummerierte Beschriftungen.

  • Seien Sie vernünftig mit den Screenshots, die Sie einschließen möchten. Screenshots können schnell veraltet sein.

Best Practices für Videos oder Animationen:

  • Videos sollten weniger als 5 Minuten lang sein.

Beispiele

Erstellen Sie scannbare Inhalte

Erleichtern Sie Lesern das schnelle Auffinden von Inhalten, indem Sie Text unter Abschnittsüberschriften organisieren und Listen und Tabellen verwenden. Überschriften, Sätze und Absätze sollten kurz und leicht lesbar sein. Die wichtigsten Informationen sollten zuerst zur Verfügung gestellt werden.

Beispiele

Erstellen Sie Workflows, mit denen Benutzer ihre Ziele erreichen

Anwender lesen unsere Inhalte, um ein bestimmtes Ziel zu erreichen. Benutzer möchten die Inhalte finden, die sie benötigen, ihre Ziele erreichen und nach Hause zu ihren Familien gehen. Unsere Aufgabe ist es nicht, Produkte oder Funktionen zu dokumentieren. Unsere Aufgabe ist es, die Ziele der Benutzer zu dokumentieren. Workflows können Benutzer am direktesten beim Erreichen ihrer Ziele unterstützen.

Ein Workflow besteht aus mehreren Schritten oder Unteraufgaben, die die Erreichung eines Benutzerziels beschreiben. Der Umfang eines Workflows ist ein komplettes Ziel.

Beispielsweise wären die Schritte zur Erstellung eines Volumes kein Workflow, da die Erstellung eines Volume an sich kein komplettes Ziel ist. Die Schritte, um Speicher einem ESX-Server zur Verfügung zu stellen, können ein Workflow sein. Zu den Schritten gehören nicht nur die Erstellung eines Volumes, sondern auch der Export des Volumes, die Einstellung aller erforderlichen Berechtigungen, die Erstellung einer Netzwerkschnittstelle usw.

Workflows stammen aus Anwendungsfällen von Kunden. Ein Workflow zeigt nur die beste Möglichkeit, das Ziel zu erreichen.

Organisieren Sie Inhalte basierend auf dem Ziel des Benutzers

Helfen Sie Benutzern, Informationen schnell zu finden, indem Sie Inhalte auf der Grundlage des Ziels organisieren, das der Benutzer erreichen möchte. Diese Norm gilt für das Inhaltsverzeichnis (Navigation) einer Dokumentations-Site sowie für die einzelnen Seiten, die auf der Website erscheinen.

Organisieren Sie den Inhalt wie folgt:

Der erste Eintrag in der linken Navigation (High Level)

Organisieren Sie Inhalte, um die Ziele zu erreichen, die der Benutzer erreichen möchte. Beispielsweise könnte der erste Eintrag in der Navigation für die Website „erste Schritte“ oder „Daten schützen“ sein.

Die Einträge der zweiten Ebene in der Navigation der Dokumentations-Site (mittlere Ebene)

Organisieren Sie Inhalte rund um die umfassenden Aufgaben, die die Ziele bilden.

Der Abschnitt „erste Schritte“ kann beispielsweise die folgenden Seiten umfassen:

  • Installation vorbereiten

  • Installieren und Einrichten von <product name>

  • Lizenzierung einrichten

  • Was Sie als Nächstes tun können

Einzelne Seiten (detaillierte Ebene)

Organisieren Sie auf jeder Seite den Inhalt um die einzelnen Aufgaben, aus denen sich die breit angelegten Aufgaben zusammensetzen. Zum Beispiel die Inhalte, die Benutzer für die Installation vorbereiten oder die Disaster Recovery einrichten müssen.

Eine Seite kann eine einzelne Aufgabe oder mehrere Aufgaben beschreiben. Wenn mehrere Aufgaben vorhanden sind, sollten sie in separaten Abschnitten auf der Seite beschrieben werden. Jeder Abschnitt sollte sich auf einen einzelnen Lern- oder Doing-Aspekt der breiten Aufgabe konzentrieren. Dazu können einige konzeptionelle und referenzbasierte Informationen gehören, die für die Durchführung der Aufgabe erforderlich sind.

Schreiben Sie für ein globales Publikum

Unsere Dokumentation wird von vielen Benutzern gelesen, deren primäre Sprache nicht Englisch ist. Wir übersetzen unsere Inhalte in andere Sprachen mit Hilfe von maschinellen Übersetzungstools oder menschlicher Übersetzung. Um unsere globale Zielgruppe zu unterstützen, schreiben wir leicht lesbare und leicht zu übersetzende Inhalte.

Befolgen Sie diese Richtlinien, um für eine globale Zielgruppe zu schreiben:

  • Schreiben Sie kurze, einfache Sätze.

  • Verwenden Sie die Standardgrammatik und Satzzeichen.

  • Verwenden Sie ein Wort für eine Bedeutung und eine Bedeutung für ein Wort.

  • Verwenden Sie allgemeine Kontraktionen.

  • Verwenden Sie Grafiken, um Text zu klären oder zu ersetzen.

  • Vermeiden Sie das Einbetten von Text in Grafiken.

  • Vermeiden Sie es, drei oder mehr Substantive in einer Zeichenkette zu haben.

  • Unklare Vorläufer vermeiden.

  • Vermeiden Sie Jargon, Kolloquialismen und Metaphern.

  • Vermeiden Sie nicht-technische Beispiele.

  • Verwenden Sie keine harten Rückstände und Abstände.

  • Verwenden Sie weder Humor noch Ironie.

  • Verwenden Sie keine diskriminierenden Inhalte.

  • Verwenden Sie keine geschlechtsbezogene Sprache, es sei denn, Sie schreiben für eine bestimmte Persona.

Richtlinien von A bis Z

Akronyme und Abkürzungen

Verwenden Sie bekannte Akronyme und Abkürzungen, um sich vertraut zu machen, vermeiden Sie jedoch obskure Akronyme, die sich negativ auf die Klarheit und die Befindbarkeit auswirken könnten. Weitere Konventionen für Akronyme und Abkürzungen finden Sie im "Microsoft-Schreibstil-Leitfaden".

Aktive Stimme (im Vergleich zu passiver Stimme)

Siehe Aktiv schreiben.

Ermahnungen

Ermahnungen sind ein mächtiges Werkzeug, wenn sie richtig verwendet werden. Sie können auf wichtige Informationen aufmerksam machen, hilfreiche Tipps geben oder Benutzer vor potenziellen Gefahren warnen. Bei Überbeanspruchungen verlieren sie ihre Auswirkungen und können zu Ermüdung des Benutzers führen. Hier sind einige Richtlinien, um die effektive Verwendung von Ermahnungen zu gewährleisten.

Verwenden Sie die folgenden Bezeichnungen, um Ermahnungen vom Hauptinhaltsfluss zu trennen:

  • HINWEIS: Verwenden Sie den HINWEIS, um wichtige Informationen hervorzuheben, die sich vom Rest des Textes abheben müssen. Verwenden Sie jedoch keine HINWEISE für „gut zu wissen“-Informationen, die für Benutzer nicht unbedingt erforderlich sind, um eine Aufgabe zu verstehen oder abzuschließen. Der Zweck einer NOTIZ besteht darin, die Aufmerksamkeit des Lesers auf kritische Punkte zu lenken, die er sonst übersehen könnte.

  • TIPP-Tipps sollten sparsam, wenn überhaupt, verwendet werden, da unsere Richtlinie ist, Best-Practice-Informationen standardmäßig zu dokumentieren. Verwenden Sie bei Bedarf den TIPP, um Best-Practice-Informationen hervorzuheben, die Benutzern helfen, ein Produkt zu verwenden oder einen Schritt oder eine Aufgabe einfacher und effizienter durchzuführen. Ein TIPP sollte nützliche Ratschläge oder Verknüpfungen geben, die das Benutzererlebnis verbessern können.

  • VORSICHT VORSICHT VORSICHT Verwenden Sie VORSICHT, um den Benutzer vor Bedingungen oder Maßnahmen zu warnen, die zu unerwünschten Ergebnissen führen können, einschließlich Verletzungen oder Schäden an Geräten. VORSICHT ist geboten, um auf potenzielle Gefahren aufmerksam zu machen, die der Benutzer vermeiden muss, um Schäden oder Störungen zu vermeiden.

  • BEST PRACTICES Nutzen Sie BEST PRACTICES, um optimale Methoden zum Abschließen von Aufgaben oder zur Verwendung eines Produkts hervorzuheben. Es handelt sich dabei nicht um bloße Vorschläge, sondern um Strategien, die von Experten oder Branchenstandards validiert wurden.

    • Was macht eine BEST PRACTICE aus? Es handelt sich um eine umsetzbare, aufgabenspezifische Strategie, die klare Vorteile bietet und von zuverlässigen Quellen unterstützt wird.

    • Wann kann ich sie verwenden? Sie können BEST PRACTICES für alle Inhaltstypen und alle Zielgruppen anwenden. Wie TIPPS, verwenden Sie sie sparsam, um ihre Bedeutung zu erhalten.

    • Wie formatige ich sie? Präsentieren Sie BEST PRACTICES in einem konsistenten, benutzerfreundlichen Format. Dies kann je nach Kontext eine Aufzählungsliste, eine nummerierte Liste oder ein Absatz sein.

Zusätzliche Richtlinien

  • Verwenden Sie nur unterstützte Ermahnungen. Jede andere Art von Formatierung wird nicht unterstützt.

  • Vermeiden Sie eine Überbeanspruchung von Ermahnungen. Überbeanspruchung kann dazu führen, dass Benutzer diese wichtigen Abschnitte überspringen, da sie sie als „Junk-Schublade“ unserer Dokumente sehen.

  • Als Faustregel gilt, die Anzahl der Ermahnungen auf maximal 3 pro Seite zu begrenzen.

  • Geben Sie klare und präzise Informationen innerhalb der Mahnung. Die Botschaft sollte kurz und bündig sein, so dass die Benutzer schnell die Bedeutung der bereitgestellten Informationen verstehen können.

  • Vermeiden Sie AsciiDoc-Ermahnungen in einer Tabelle. Wenn der Inhalt als Hinweis, Tipp oder Vorsicht gekennzeichnet werden muss, verwenden Sie Hinweis:, Tipp:, oder Achtung: als Inline-Einleitung in den Text.

Nach (im Vergleich zu „einmal“)

  • Verwenden Sie "nach", um eine Chronologie anzuzeigen: "Schalten Sie Ihren Computer ein, nachdem Sie ihn angeschlossen haben."

  • Verwenden Sie „einmalig“, um „einmalig“ zu bedeuten.

Außerdem

  • Verwenden Sie „auch“, um „zusätzlich“ zu bedeuten.

  • Verwenden Sie nicht „auch“, um „alternativ“ zu bedeuten.

Und/oder

Wählen Sie den präziseren Begriff aus, wenn es einen gibt. Wenn keiner der beiden Begriffe präziser ist als der andere, verwenden Sie „und/oder“.

Als

Verwenden Sie „As“ nicht, um „weil“ zu bedeuten.

Mit (im Gegensatz zu „mit“ oder „mit“)

  • Verwenden Sie "by using", wenn die Entität, die die Verwendung macht, der Betreff ist: "Sie können neue Komponenten zum Repository hinzufügen, indem Sie das Komponenten-Menü verwenden."

  • Sie können einen Satz entweder mit „Verwenden“ oder „mit“ beginnen, was bei Produktnamen manchmal akzeptabel ist: „Mit SnapDrive können Sie virtuelle Festplatten und Snapshot-Kopien in einer Windows-Umgebung verwalten.“

Can (versus „könnte“, „darf“, „sollte“ oder „muss“)

  • Verwenden Sie "CAN", um die Fähigkeit anzuzeigen: "Sie können Ihre Änderungen jederzeit während dieses Verfahrens festlegen."

  • Verwenden Sie „Might“, um die Möglichkeit anzuzeigen: „Das Herunterladen mehrerer Programme kann sich auf die Verarbeitungszeit auswirken.“

  • Verwenden Sie „may“ nicht, was zweideutig ist, da es entweder Fähigkeit oder Erlaubnis bedeuten könnte.

  • Verwenden Sie „sollte“, um eine empfohlene, aber optionale Aktion anzuzeigen. Ziehen Sie stattdessen eine alternative Phrase in Betracht, z. B. „Wir empfehlen“.

  • Vermeiden Sie es, "muss" zu verwenden, weil es ist Passiv. Überlegen Sie, den Gedanken als eine Anweisung mit zwingender Stimme zu rerestieren. Wenn Sie „Must“ verwenden, können Sie damit eine erforderliche Aktion oder Bedingung angeben.

Großschreibung

Verwenden Sie für fast alles eine Kapitalisierung im Stil von Satz (klein geschrieben). Nur Kapital:

  • Das erste Wort aus Sätzen und Überschriften, einschließlich Tabellenüberschriften

  • Das erste Wort der Listenelemente, einschließlich Satzfragmente

  • Richtige Substantive

  • DOC-Titel und Untertitel (Kapitalisierung aller wichtigsten Wörter und Präpositionen von fünf oder mehr Buchstaben)

  • UI-Elemente, aber nur, wenn sie in der Schnittstelle groß geschrieben werden. Verwenden Sie andernfalls Kleinbuchstaben.

Warnhinweise

Siehe Ermahnungen.

Kontraktionen

Nutzung Kontraktionen Als Teil des Schreibens im Gespräch.

Sicherstellen (im Gegensatz zu „bestätigen“ oder „überprüfen“)

  • Verwenden Sie „Sicherstellen“, um „um sicher zu sein“. Fügen Sie gegebenenfalls „das“ hinzu: „Stellen Sie sicher, dass genügend Freiraum um die Abbildungen herum vorhanden ist.“

  • Verwenden Sie niemals „Sicherstellen“, um ein Versprechen oder eine Garantie einzulegen: „Verwenden Sie Cloud Manager, um sicherzustellen, dass Sie NFS und CIFS Volumes auf ONTAP Clustern bereitstellen können.“

  • Verwenden Sie „confirm“ oder „verify“, wenn Sie meinen, dass der Benutzer etwas überprüfen sollte, das bereits existiert oder bereits geschehen ist: „Verifizieren Sie, dass NFS auf dem Cluster eingerichtet ist.“

Grafik

Siehe Verwenden Sie viele Visuals.

Grammatik

Wenn nicht anders angegeben, befolgen Sie die Grammatik-, Zeichensetzung- und Rechtschreibkonventionen, die in aufgeführt sind:

Wenn nicht

Verwenden Sie nicht „wenn nicht“, um sich auf den vorherigen Satz zu beziehen:

  • Anstatt dies: "Der Computer sollte ausgeschaltet sein. Wenn nicht, schalten Sie es aus.“

  • Do this: "Stellen Sie sicher, dass der Computer ausgeschaltet ist."

If (versus „ob“ oder „Wann“)

  • Verwenden Sie „if“, um eine Bedingung anzuzeigen, z. B. in „if this, then that“-Konstruktionen.

  • Verwenden Sie „ob“, wenn eine angegebene oder implizierte „oder nicht“-Bedingung vorliegt. Um die Übersetzung zu erleichtern, ist es oft am besten, „ob“ oder „nicht“ mit „ob“ allein zu ersetzen.

  • Verwenden Sie „Wann“, um einen Verlauf der Zeit anzuzeigen.

Eine zwingende Stimme

Siehe Aktiv schreiben.

Funktionen und Releases werden zukünftig veröffentlicht

Beziehen Sie sich nicht auf den Zeitpunkt oder den Inhalt der kommenden Produktveröffentlichungen oder -Funktionen, außer zu sagen, dass eine Funktion oder Funktion „derzeit nicht unterstützt“ wird.

KB-Artikel: Verweisen auf

Greifen Sie gegebenenfalls auf Inhalte in KB (NetApp Knowledgebase)-Artikeln zu. Für Ressourcen-Seiten und GitHub-Inhalte, setzen Sie den Link in Running Text.

Listen

Listen von Informationen sind in der Regel einfacher zu scannen und absorbieren als Textblöcke. Überlegen Sie, wie Sie komplexe Informationen vereinfachen können, indem Sie sie in Listenform präsentieren. Hier sind einige allgemeine Richtlinien, aber nutzen Sie Ihr Urteil:

  • Stellen Sie sicher, dass der Grund für die Liste klar ist. Führen Sie die Liste mit einem vollständigen Satz, einem Satzfragment mit einem Doppelpunkt oder einer Überschrift ein.

  • Wenn Sie eine Liste in einer Liste verwenden, begrenzen Sie die Struktur auf maximal zwei Tiefenebenen, um Klarheit und Lesbarkeit zu erhalten. Wenn Sie mehr Ebenen benötigen, sollten Sie die Inhalte neu organisieren, damit Benutzer leichter navigieren und verstehen können.

  • Jede Liste, einschließlich verschachtelter Listen, sollte zwischen zwei und sieben Einträge enthalten. Im Allgemeinen, je kürzer die Informationen in jedem Eintrag, desto mehr Einträge können Sie hinzufügen, während die Liste scannable. Wenn eine Liste mehrere Einträge enthält, die verschachtelte Listen enthalten, sollten Sie Abschnitte oder Blocktitel verwenden, um das gesamte Element in verbrauchsstärkere Teile zu unterteilen.

  • Listeneinträge sollten so scannbar wie möglich sein. Vermeiden Sie Textblöcke, die in der Art und Weise, Listen Einträge scannable erhalten.

  • Listeneinträge sollten mit einem Großbuchstaben beginnen, und Listeneinträge sollten grammatikalisch parallel sein. Beginnen Sie beispielsweise jeden Eintrag mit einem Substantiv oder einem Verb:

    • Wenn es sich bei allen Listeneinträgen um vollständige Sätze handelt, beenden Sie diese mit Perioden.

    • Wenn es sich bei allen Listeneinträgen um Satzfragmente handelt, sollten Sie diese nicht mit Punkten beenden.

  • Listeneinträge sollten auf logische Weise geordnet werden, z. B. alphabetisch oder chronologisch.

Lokalisierung

Siehe Schreiben Sie für ein globales Publikum.

Minimalismus

Siehe Minimale Schreibvorgänge.

Ziffern enthalten

  • Verwenden Sie arabische Ziffern für 10 und alle Zahlen größer als 10, mit folgenden Ausnahmen:

    • Wenn Sie einen Satz mit einer Zahl beginnen, verwenden Sie ein Wort, nicht eine arabische Zahl.

    • Verwenden Sie Wörter (keine Ziffern) für ungefähre Zahlen.

  • Verwenden Sie Wörter für Zahlen, die weniger als 10 sind.

  • Wenn ein Satz eine Mischung aus Zahlen kleiner als 10 und größer als 10 enthält, verwenden Sie arabische Ziffern für alle Zahlen.

  • Weitere Konventionen für Nummern finden Sie unter "Microsoft-Schreibstil-Leitfaden".

Plagiat

Wir dokumentieren NetApp Produkte und die Interaktion von NetApp Produkten mit Produkten von Drittanbietern. Wir dokumentieren keine Produkte von Drittanbietern. Niemals sollten wir Inhalte von Drittanbietern in unsere Dokumentation kopieren und einfügen müssen, und das sollten wir niemals tun.

Voraussetzungen

Die Voraussetzungen bestimmen die Bedingungen, die vorhanden sein müssen oder die Aktionen, die Benutzer vor dem Start der aktuellen Aufgabe abgeschlossen haben müssen.

  • Identifizieren Sie die Art des Inhalts mithilfe einer Überschrift, z. B. „Voraussetzungen“, „bevor Sie beginnen“ oder „bevor Sie beginnen“.

  • Verwenden Sie passive Stimme als Vorformulierung, wenn es sinnvoll ist, dies zu tun:

    • „NFS oder CIFS müssen auf dem Cluster eingerichtet werden.“

    • „Um den Cluster zu Cloud Manager hinzuzufügen, müssen Sie die Cluster-Management-IP-Adresse und das Passwort für das Admin-Benutzerkonto besitzen.“

  • Klären Sie bei Bedarf die Voraussetzung: „NFS oder CIFS müssen auf dem Cluster eingerichtet werden. Sie können NFS und CIFS mit System Manager oder der CLI einrichten.“

  • Überlegen Sie andere Möglichkeiten, um die Informationen zu präsentieren, zum Beispiel, ob es sinnvoll wäre, den Inhalt als ersten Schritt in der aktuellen Aufgabe zu resagen:

    • Voraussetzung: „Sie müssen über die erforderlichen Berechtigungen verfügen, bevor Sie Ihren ersten Cluster bereitstellen.“

    • Schritt: „Bereitstellen der erforderlichen Berechtigungen für die Bereitstellung des ersten Clusters“

Vorher (versus „vorher“, „vorher“ oder „vorher“)

  • Wenn möglich, ersetzen Sie „prior“ durch „before“.

  • Wenn Sie „vorher“ nicht verwenden können, verwenden Sie „vorher“ als Adjektiv, um auf etwas zu verweisen, das früher oder in einer höheren Reihenfolge aufgetreten ist.

  • Verwenden Sie „previous“, um etwas anzuzeigen, das zu einem nicht festgelegten Zeitpunkt früher aufgetreten ist.

  • Verwenden Sie „vorhergehend“, um etwas anzuzeigen, das unmittelbar vorher aufgetreten ist.

Satzzeichen

Einfach Im Allgemeinen, je mehr Satzzeichen enthalten sind, desto mehr Gehirnzellen, die es braucht, um zu verstehen.

  • Verwenden Sie ein serielles Komma (Oxford-Komma) vor der Verbindung („and“ oder „or“) in einer Narrativliste mit mindestens drei Elementen.

  • Beschränken Sie die Verwendung von Semikolons und Doppelpunkte.

  • Wenn nicht anders angegeben, befolgen Sie die Grammatik-, Zeichensetzung- und Rechtschreibkonventionen, die in aufgeführt sind:

Seit

Verwenden Sie „seit“, um einen Verlauf der Zeit anzuzeigen. Verwenden Sie „Da“ nicht, um „weil“ zu bedeuten.

Rechtschreibung

Wenn nicht anders angegeben, befolgen Sie die Grammatik-, Zeichensetzung- und Rechtschreibkonventionen, die in aufgeführt sind:

Das (im Vergleich zu „welches“ oder „wer“)

  • Verwenden Sie „das“ (ohne nachfolgendes Komma), um Klauseln einzuführen, die für den Satz erforderlich sind, um Sinn zu machen.

  • Verwenden Sie "das", auch wenn der Satz in Englisch ohne es klar ist: "Überprüfen Sie, ob der Computer ausgeschaltet ist."

  • Verwenden Sie „which“ (mit nachhängenden Kommas), um Klauseln einzuführen, die unterstützende Informationen hinzufügen, aber nicht erforderlich sind, damit der Satz sinnvoll ist.

  • Verwenden Sie „Wer“, um Klauseln einzuführen, die sich auf Personen beziehen.

Marken

In den meisten technischen Inhalten enthalten wir keine Markensymbole, da die rechtlichen Aussagen in unseren Vorlagen ausreichend sind. Bei der Verwendung befolgen wir jedoch sämtliche Nutzungsregeln "NetApp geschützte Bedingungen":

  • Verwenden Sie geschützte Begriffe (mit oder ohne Symbol) nur als Adjektive, niemals als Substantive, Verben oder verbale.

  • Verwenden Sie keine Abkürzungen, Silbentrennung oder Kursivierung von Markenbegriffen.

  • Verwenden Sie keine pluralisierenden Markenbegriffe. Wenn ein Plural-Formular erforderlich ist, verwenden Sie den geschützten Namen als Adjektiv, das ein Plural-Substantiv ändert.

  • Verwenden Sie keine besitzergreifende Form eines markengeschützten Begriffs. Sie können die Possessive Form von Firmennamen wie NetApp verwenden, wenn die Namen im allgemeinen Sinne verwendet werden, anstatt als geschützte Begriffe.

Benutzeroberfläche

Wenn Sie eine Benutzeroberfläche dokumentieren, verlassen Sie sich so weit wie möglich auf die Benutzeroberfläche, um den Benutzer zu führen.

Allgemeine Richtlinien

Verwenden Sie beim Dokumentieren von UIs einen einfachen und minimalen Stil.

Details

  • Gehen Sie davon aus, dass der Benutzer die Benutzeroberfläche beim Lesen des Inhalts verwendet:

    • Führen Sie den Benutzer nicht Schritt für Schritt durch einen Assistenten oder einen Bildschirm. Nennen Sie nur wichtige Dinge, die von der Oberfläche nicht ersichtlich sind.

    • Fügen Sie nicht „Klicken Sie auf OK“, „Klicken Sie auf Speichern“ oder „das Volume wird erstellt“ oder irgendetwas anderes, das für jemanden, der diese Aufgabe ausführt, offensichtlich ist, bei.

    • Erfolg übernehmen. Wenn Sie nicht erwarten, dass ein Vorgang die meiste Zeit ausfällt, dokumentieren Sie den Fehlerpfad nicht. Angenommen, die Schnittstelle bietet die richtige Orientierung.

  • Verwenden Sie überhaupt keinen „Klick“. Verwenden Sie immer „Auswählen“, da dieses Wort Maus, Berührung, Tastatur und jede andere Art der Auswahl umfasst.

  • Konzentrieren Sie den Inhalt auf einen Workflow, der den Kundenfall anspricht und den Benutzer an die richtige Stelle in der Schnittstelle zum Starten des Workflows bringen soll.

  • Dokumentieren Sie immer den besten Weg, um das Benutzerziel zu erreichen.

  • Wenn der Workflow eine wichtige Entscheidung erfordert, achten Sie darauf, eine Entscheidungsregel zu dokumentieren.

  • Verwenden Sie die Mindestanzahl der für die meisten Benutzer erforderlichen Schritte.

Benennen von UI-Elementen

Vermeiden Sie das Dokumentieren des Granularitätsniveaus, der UI-Elemente erfordert.

Details

Verlassen Sie sich auf die Schnittstelle, um den Benutzer durch die Besonderheiten der Interaktion zu führen. Wenn Sie diese spezifische Version erhalten müssen, benennen Sie die Bezeichnung auf dem Element. Beispiel: „Wählen Sie das gewünschte Volume aus“ oder „Wählen Sie „vorhandenes Volume verwenden“.“ Es ist nicht notwendig, Menüs oder Optionsfelder oder Kontrollkästchen zu benennen, verwenden Sie einfach die Bezeichnung.

Verwenden Sie für Symbole, die Benutzer auswählen müssen, ein Bild des Symbols. Versuchen Sie nicht, es zu benennen. Diese Regel gilt für Symbole wie Pfeil, Bleistift, Getriebe, Kabob, Hamburger, Und so weiter.

Darstellung der angezeigten Beschriftungen

Befolgen Sie beim Identifizieren von Etiketten die Rechtschreibung und Groß-/Kleinschreibung, die von der Benutzeroberfläche verwendet werden.

Details

Wenn Ellipsen auf eine Bezeichnung folgen, nehmen Sie bei der Benennung des Objekts keine Ellipsen ein. Ermuntern Sie Entwickler, die Kapitalisierung im Titelstil für Benutzeroberflächenetiketten zu verwenden, um das Schreiben über sie einfacher zu machen.

Verwenden von Bildschirmaufnahmen

Verwenden Sie Bildschirmaufnahmen sparsam.

Details

Eine gelegentliche Bildschirmaufzeichnung („Screenshot“) gibt Benutzern die Gewissheit, dass sie sich am richtigen Ort in einer Benutzeroberfläche befinden, wenn sie während eines Workflows Schnittstellen starten oder ändern. Verwenden Sie keine Bildschirmaufnahmen, um zu zeigen, welche Daten eingegeben werden sollen oder welcher Wert ausgewählt werden soll.

Während (im Vergleich zu „obwohl“)

  • Verwenden Sie „while“, um ein zeitliches Auftreten anzuzeigen.

  • Verwenden Sie „Obwohl“, um eine Aktivität darzustellen, die fast zur gleichen Zeit oder kurz nach einer anderen Aktivität stattfindet.