TOC

Technische Richtlinien von DigitalOcean

DigitalOcean freut sich, seine Sammlung technischer Artikel zur Serververwaltung und zum Software-Engineering weiter auszubauen. Um sicherzustellen, dass DigitalOcean-Artikel eine einheitliche Qualität und einen einheitlichen Stil aufweisen, haben wir die folgenden Richtlinien entwickelt.

Dieses Handbuch enthält drei Abschnitte:

  • Style, unser übergeordneter Ansatz zum Schreiben technischer Tutorials

  • Structure, eine Erklärung unseres Layouts und Inhalts

  • Formatting and Terminology, eine Markdown- und Terminologie-Referenz

Um schnell veröffentlicht zu werden, sollten Autoren der DigitalOcean-Community die Abschnitte zu Stil und Struktur vollständig lesen. Unseretemplates sind als Ausgangspunkt für einen Artikel nützlich, und der Formatierungsabschnitt dieses Handbuchs kann zusammen mit unserenMarkdown previewer als Referenz beim Schreiben verwendet werden. Wir haben auch eintechnical best practices guidefür unsere technikorientierten Empfehlungen.

Stil

DigitalOcean-Artikel sollten sein:

  • Umfassend und geschrieben für alle Erfahrungsstufen

Unsere Artikel sind so klar und detailliert wie möglich geschrieben, ohne dass Annahmen über das Hintergrundwissen des Lesers gemacht werden.

Wir schließen ausdrücklich jeden Befehl ein, den ein Leser benötigt, um von seiner ersten SSH-Verbindung auf einem brandneuen Server zum endgültigen, funktionierenden Setup zu gelangen. Wir bieten den Lesern auch alle Erklärungen und Hintergrundinformationen, die sie zum Verständnis des Tutorials benötigen. Das Ziel ist, dass unsere Leser lernen, nicht nur kopieren und einfügen.

  • Technisch detailliert und korrekt

Alle unsere Tutorials werden auf neuen Servern getestet, um sicherzustellen, dass sie von Grund auf funktionieren. Jeder Befehl sollte eine detaillierte Erklärung enthalten, einschließlich der erforderlichen Optionen und Flags. Wenn Sie den Leser auffordern, einen Befehl auszuführen oder eine Konfigurationsdatei zu ändern, erläutern Sie zunächst, was er tut oder warum er diese Änderungen vornimmt.

  • Praktisch, nützlich und in sich geschlossen

Sobald ein Leser einen DigitalOcean-Artikel fertiggestellt hat, sollte er etwas von Anfang bis Ende installiert oder eingerichtet haben. Wir betonen einen praktischen Ansatz: Am Ende eines Artikels sollten wir dem Leser eine brauchbare Umgebung oder ein Beispiel zum Bauen hinterlassen.

Für den Verfasser bedeutet dies, dass sein Artikel sein Thema ausführlich behandeln und, falls erforderlich, mit einem anderen DigitalOcean-Artikel verknüpft werden muss, um die Voraussetzungen zu schaffen. Autoren sollten Leser nicht ins Ausland schicken, um Informationen zu sammeln, die dem Artikel leicht hinzugefügt werden könnten.

  • Freundlich aber formell

Unsere Tutorials zielen auf einen freundlichen, aber formellen Ton. Dies bedeutet, dass Artikel keine Fachsprache, Meme oder übermäßigen Witze enthalten. Dies bedeutet auch, dass wir im Gegensatz zu Blog-Posts nicht die erste Person als Singular verwenden (z. "Ich denke …"). Stattdessen verwenden wir die erste Person Plural (z. „Wir installieren ...) oder eine zweite Person (z. "Sie werden konfigurieren ...").

Struktur

DigitalOcean-Tutorials haben eine konsistente Struktur, die sich aus den folgenden Abschnitten zusammensetzt:

  • Titel

  • Einführung

  • Ziele (optional)

  • Voraussetzungen

  • Schritt 1 - Das erste tun

  • Schritt 2 - Das Nächste tun

  • …

  • Schritt n - Das Letzte tun

  • Fazit

Unserearticle templateshaben dieses Layout in Markdown, das Sie als Ausgangspunkt für Ihre eigenen Artikel verwenden können. DasFormatting section of this guide enthält detailliertere Informationen zu unseren Formatierungskonventionen.

Titel

Ein typischer Titel folgt diesem Format:How To <Accomplish a Task> with <Software> on <Distro>.

Überlegen Sie sich beim Schreiben Ihres Titels genau, was der Leser erreichen kann, indem Sie Ihrem Tutorial folgen. Versuchen Sie, das Ziel des Tutorials in den Titel aufzunehmen, nicht nur die Tools, mit denen der Leser dieses Ziel erreicht.

Wenn es in Ihrem Tutorial beispielsweise um die Installation von Caddy geht, liegt das Ziel wahrscheinlich beihost a website. Wenn es in Ihrem Tutorial um die Installation von FreeIPA geht, ist das Ziel möglicherweiseset up centralized Linux authentication. Titel, die das Ziel enthalten (wie „https://www.digitalocean.com/community/tutorials/how-to-create-a-status-page-with-cachet-on-debian-8[How To Create a Status Page mit Cachet unter Debian 8]) sind für den Leser im Allgemeinen informativer als Titel, die dies nicht tun (wie „Wie installiert und richtet man Cachet unter Debian 8 ein“).

Einführung und Ziele

Der erste Abschnitt jedes Tutorials istIntroduction, der normalerweise 1 bis 3 Absätze lang ist.
Der Zweck der Einführung besteht darin, die folgenden Fragen für den Leser zu beantworten:

  • Was ist das Ziel des Tutorials? Was wird der Leser erreichen, wenn er ihm folgt?

  • Um welche Software handelt es sich und was macht jede Komponente (kurz)?

  • Was sind die Vorteile der Verwendung dieser speziellen Software in dieser Konfiguration? Was sind einige praktische Gründe, warum der Leser diesem Tutorial folgen sollte?

Einige Tutorials verwenden den optionalen AbschnittGoals, um den Kontext, die Hintergrunderklärung und die Motivation des Tutorials von den Details der endgültigen Konfiguration zu trennen. Sie sollten diesen Abschnitt nur verwenden, wenn für Ihr Lernprogramm mehrere Server erforderlich sind, ein großer Softwarestapel vorhanden ist oder ein besonders komplizierter Zweck, eine besonders komplizierte Methode oder ein besonders kompliziertes Ergebnis vorliegt.

Einige gute Beispiele sindthis Prometheus tutorial’s introduction undthis Pydio tutorial’s goals.

Voraussetzungen

Die AbschnittePrerequisitesder DigitalOcean-Tutorials haben ein ganz bestimmtes Format und einen bestimmten Zweck.

Der Zweck besteht darin,exactly zu formulieren, was der Leser haben oder tun sollte, bevor er dem aktuellen Tutorial folgt. Das Format ist eine Liste mit Aufzählungszeichen, die der Leser als Checkliste verwenden kann. Jeder Aufzählungspunkt muss mit einem vorhandenen DigitalOcean-Lernprogramm verknüpft sein, das den erforderlichen Inhalt enthält. Auf diese Weise können Sie sich auf vorhandene Inhalte verlassen, die bekanntermaßen funktionieren, anstatt von vorne zu beginnen.

Zu den allgemeinen Voraussetzungen für Aufzählungszeichen gehören:

  • Die Anzahl der erforderlichen Server, einschließlich Verteilung, anfänglicher Serverkonfiguration und zusätzlicher erforderlicher Optionen (wie Speicheranforderungen, DO-API-Schlüssel, IPv6 oder privates Netzwerk).

  • Installation und Konfiguration der Software.

  • Erforderliche DNS-Einstellungen oder SSL-Zertifikate.

  • Zusätzliche Benutzerkonten wie GitHub, Facebook, Twitter oder andere Dienste, die Ihr Leser benötigt.

Stellen Sie beim Testen Ihres Tutorials sicher, dass Sie alle vorausgesetzten Tutorials genau wie geschrieben befolgen, damit jeder den gleichen Ausgangspunkt verwendet. Wenn Sie eine Variable geändert oder einen optionalen Schritt unter einer der Voraussetzungen ausgeführt haben, müssen Sie dies beachten.

Unsere Lernprogramme für die Systemadministration führen den Leser von einer Neuimplementierung eines Vanilla-Distributionsimages zu einem funktionierenden Setup. Sie sollten daher mit der ersten SSH-Verbindung zum Server beginnen oder ein vorausgesetztes Lernprogramm enthalten, das dies tut.

Sie sehen gute Beispiele für Voraussetzungen für:

Schritte

Die AbschnitteStepind die Teile Ihres Tutorials, in denen Sie beschreiben, was der Leser tun muss.

Beginnen Sie jeden Schritt mit einem einleitenden Satz, der beschreibt, was der Schritt abdeckt und welche Rolle er beim Erreichen des Gesamtziels des Tutorials spielt. Beenden Sie jeden Schritt mit einem Übergangssatz, der beschreibt, was der Leser erreicht hat und wohin er als nächstes geht. Vermeiden Sie es, den Schritttitel in diesen Einführungen und Übergängen zu wiederholen, und beginnen oder beenden Sie Schritte nicht mit kontextlosen Anweisungen, Befehlen oder Ausgaben.

Alle Befehle in einem Schritt sollten in einer eigenen Zeile in einem eigenen Codeblock stehen, und vor jedem Befehl sollte eine Beschreibung stehen. Führen Sie in ähnlicher Weise eine Datei oder ein Skript immer ein, indem Sie deren allgemeinen Zweck beschreiben, und erläutern Sie dann alle Änderungen, die der Leser an der Datei vornehmen wird. Ohne diese Erläuterungen können Leser ihren Server auf lange Sicht nicht anpassen, aktualisieren oder Fehler beheben.

Diecustom Markdown and formatting guidelinesvon DigitalOcean sollen dazu beitragen, die Anweisungen unserer Tutorials so einfach wie möglich zu lesen. This Docker Swarm tutorial ist ein gutes Beispiel dafür, wie Sie mit unserem benutzerdefinierten Markdown zwischen Befehlen unterscheiden können, die auf mehreren verschiedenen Servern sowie lokal ausgeführt werden.

Fazit

DieConclusion sollten zusammenfassen, was der Leser erreicht hat, indem er Ihrem Tutorial folgt. Es sollte auch beschreiben, was der Leser als nächstes tun kann. Dies kann eine Beschreibung von Anwendungsfällen oder Funktionen enthalten, die der Leser untersuchen kann, Links zu anderen DigitalOcean-Tutorials mit zusätzlicher Einrichtung oder Konfiguration sowie externe Dokumentation.

Einige gute Beispiele sindthis LXD tutorial’s conclusion, https://www.digitalocean.com/community/tutorials/how-to-monitor-cpu-use-on-digitalocean-droplets#conclusion [die Schlussfolgerung dieses CPU-Überwachungs-Tutorials] und this Mosquitto tutorial’s conclusion.

Formatierung

DigitalOcean-Lernprogramme sind in der Markup-Sprache Markdown formatiert. Daring Fireball veröffentlicht einen umfassenden Markdown-Leitfaden, wenn Sie damit nicht vertraut sind. DigitalOcean verwendet auch einigecustom Markdown. Beispiele für unseren benutzerdefinierten Markdown finden Sie in den entsprechenden Abschnitten.

Überschriften

Jeder Abschnitt unserer Tutorials hat eine entsprechende Überschrift: Die Überschrift sollte eine H1-Überschrift sein; Die Einleitung sollte ein H3-Header sein. Die Ziele, Voraussetzungen, Schritte und Schlussfolgerungen sollten H2-Header haben. Sie können dieses Format in unserenMarkdown article templates sehen.

Für prozedurale Tutorials sollten Schrittüberschriften Schrittnummern (numerisch) gefolgt von einem Bindestrich (—) enthalten. Schrittüberschriften sollten auch das Gerundium verwenden, bei dem es sich um-ingWörter handelt. Ein Beispiel für einen Schrittkopf istStep 1 — Installing Nginx.

Verwenden Sie H3-Header sparsam und vermeiden Sie H4-Header. Wenn Sie Unterüberschriften verwenden müssen, vergewissern Sie sich, dass sich in diesem Abschnitt des Tutorials zwei oder mehr Überschriften dieser Ebene befinden. Alternativ können Sie auch mehrere Schritte ausführen.

Formatierung auf Zeilenebene

Bold text sollte verwendet werden für:

  • Sichtbarer GUI-Text

  • Host- und Benutzernamen wiewordpress-1 odersammy

  • Begriffslisten

  • Schwerpunkt beim Ändern des Kontexts für einen Befehl, z. B. beim Wechseln zu einem neuen Server oder Benutzer

Italics sollten nur bei der Einführung von Fachbegriffen verwendet werden. Zum Beispiel ist der Nginx-Server unserload balancer.

Die Inline-Code-Formatierung sollte verwendet werden für:

  • Befehlsnamen wieunzip

  • Paketnamen wiemysql-server

  • Optionale Befehle

  • Dateinamen und Pfade wie~/.ssh/authorized_keys

  • Beispiel-URLs wiehttp://your_domain

  • Ports wie:3000

  • Tastendrücke, die in ALL CAPS stehen sollten und ein Pluszeichen ** verwenden, wenn gleichzeitig Tasten gedrückt werden müssen, wie z. B. `+ ENTER` oderCTRL+C

Codeblöcke

Codeblöcke sollten verwendet werden für:

  • Befehle, die der Leser ausführen muss, um das Lernprogramm abzuschließen

  • Dateien und Skripte

  • Terminal-Ausgang

  • Interaktive Dialoge im Text

Auszüge und Auslassungen in Dateien können mit Ellipsen (…) angegeben werden. Wenn ein Großteil einer Datei mit den Standardeinstellungen belassen werden kann, ist es normalerweise besser, nur den Abschnitt anzuzeigen, der geändert werden muss.

Codeblock-Präfixe

Fügen Sie die Eingabeaufforderung nicht in den Codeblock ein. Verwenden Sie stattdessen DigitalOceans benutzerdefinierten Markdown für Nicht-Root-Benutzerbefehle, Root-Benutzerbefehle und benutzerdefinierte Präfixe: 

```command
sudo apt-get update
```

```super_user
adduser sammy
```

```custom_prefix(mysql>)
FLUSH PRIVILEGES;
```

So sehen die vorhergehenden Beispiele beim Rendern aus: 

sudo apt-get update
adduser sammy
FLUSH PRIVILEGES;

Codeblock-Beschriftungen

DigitalOceans Markdown umfasst auch Etiketten und sekundäre Etiketten. Sie können Codeblöcken Beschriftungen hinzufügen, indem Sie an einer beliebigen Stelle im Block eine Zeile mit[label Label text] oder[secondary_label Secondary label text] hinzufügen.

Verwenden Sie Labels, um Codeblöcke, die den Inhalt einer Datei enthalten, mit einem Dateinamen zu kennzeichnen. Verwenden Sie sekundäre Beschriftungen, um die Terminalausgabe zu markieren.

Beschriftungen sehen beim Rendern folgendermaßen aus:

Dies ist der Etikettentext 

This is one line of the file
This is another line of the file
. . .
This is a line further down the file

Beispiel für ein Sekundäretikett: 

This is the secondary label textThis is some output from a command

Farben der Codeblockumgebung

Mit dem Markdown von DigitalOcean können Sie den Hintergrund eines Codeblocks einfärben, indem Sie an einer beliebigen Stelle im Block eine Zeile mit[environment name] hinzufügen. Die Optionen fürname sindlocal,second,third,fourth undfifth.

Dies ist ein Beispiel für einen lokalen Serverbefehl: 

ssh root@your_server_ip

Dies sind Beispiele für nicht-primäre Serverbefehle, die für Multi-Server-Setups nützlich sind: 

echo "Secondary server"
echo "Third server"
echo "Fourth server"
echo "Fifth server

Hinweise und Warnungen

Mit dem DigitalOcean Markdown-Parser können benutzerdefiniertenote- undwarning-Codeblöcke verwendet werden, um sehr wichtigen Text anzuzeigen.

Hier ist ein Markdown-Beispiel für eine Notiz und eine Warnung (dies ist ein Bild):

Notes and Warnings

Hier ist das gerenderte Ergebnis:

[.note] #Note: Dies ist eine Notiz.
#

[.warning] #Warning: Dies ist eine Warnung.
#

Variablen

Markieren Sie alle Elemente, die vom Reader geändert werden müssen, z. B. Beispiel-URLs oder geänderte Zeilen in Konfigurationsdateien. Sie können dies tun, indem Sie das Wort oder die Zeile mit unserem benutzerdefinierten<^>Markdown umgeben. Beachten Sie, dass Sie nicht mehrere Zeilen mit einem Symbolpaar markieren können. Daher müssen Sie jede Zeile einzeln markieren.

Wenn Sie auf eine Variable in einem Kontext verweisen, in dem Sie normalerweise auch die Formatierung vonin-line codeverwenden würden, sollten Sieboth styles verwenden. Stellen Sie sicher, dass Ihr Tutorial so zugänglich wie möglich ist, indem Sie eine Sprache wie "im vorhergehenden Codeblock hervorgehoben" anstelle von "oben rot hervorgehoben" verwenden.

Vermeiden Sie Sprachen wie "unten rot hervorgehoben"

Bilder und andere Vermögenswerte

Bilder können schnell einen Punkt veranschaulichen oder in einem Schritt zusätzliche Klarheit schaffen. Verwenden Sie Bilder für Screenshots von GUIs, interaktive Dialoge und Diagramme von Server-Setups. Verwenden Sie keine Bilder für Screenshots von Code, Konfigurationsdateien, Ausgaben oder anderen Elementen, die kopiert und in den Artikel eingefügt werden können.

Wenn Sie Bilder in Ihr Tutorial aufnehmen, befolgen Sie bitte diese Richtlinien:

  • Verwenden Sie beschreibenden Alternativtext, damit Leser, die einen Bildschirmleser verwenden, sich auf den Alternativtext und nicht auf das Bild verlassen können.

  • Verwenden Sie das Dateiformat.png

  • Host-Bilder aufimgur

  • Stellen Sie das Bild so kurz wie möglich ein

Wenn Sie ein Modell eines Diagramms für Ihr Lernprogramm erstellen, erstellen wir ein Diagramm im DigitalOcean-Stil. Wir werden auch alle Bilder zum Zeitpunkt der Veröffentlichung auf DigitalOcean-Server hochladen.

Hier ist ein Markdown-Beispiel zum Einfügen von Bildern in Ihr Tutorial: 

![Alt text for screen readers](http://imgur.com/your_image_url)

Gelegentlich soll der Leser Zugriff auf eine Konfigurationsdatei haben, die zu lang ist, um im Hauptteil des Lernprogramms angezeigt zu werden. DigitalOcean wird diese Datei auf unserem Assetserver hosten. Sie können die Standard-Link-Formatierung zum Verknüpfen mit der Datei verwenden.

Terminologie

Benutzer, Hostnamen und Domänen

Unser Standardbenutzername istsammy. Sie können auch etwas Beschreibendes auswählen, wenn dies hilfreich ist, z. B.webdav-kai odernsd.

your_server ist der Standardhostname. Sie sollten jedoch etwas Beschreibendes auswählen, insbesondere bei Setups mit mehreren Servern wiedjango_replica_1.

your_domain ist die Standarddomäne. Bei Multi-Server-Setups können Sie zwischenprimary-1.your_domain undreplica-1.your_domain wählen. Währendexample.com eine gültige Domäne für die Dokumentation ist, wird durch die Verwendung vonyour_domain in Lernprogrammen klarer, dass der Leser die Domäne in Beispielen ändern sollte.

Verwenden Sie die Markierung, wenn Sie diese in Konfigurationsdateien verwenden, wie folgt:

Beispiel-Konfigurationsdatei 

ip: your_server_ip
domain: primary-1.your_domain

Dies macht den Lesern klar, dass sie etwas ändern sollten.

IP-Adressen und URLs

your_server_ip mit Inline-Code-Formatierung und Variablenhervorhebung ist die Standardmethode zum Anzeigen einer IP-Adresse. Sie können mehrere IP-Adressen mit Namen wieprimary_private_ip undreplica_private_ip anzeigen. Wenn Sie realistischere IP-Adressen veranschaulichen möchten, verwenden Sie eine Adresse inone of the two blocks reserved for documentation as per RFC-5737. Insbesondere empfehlen wir203.0.113.0/24 zum Beispiel öffentliche Adressen und198.51.100.0/24 zum Beispiel private Adressen.

Beispiel-URLs, die eine Variable enthalten, die der Leser anpassen muss, sollten eine Code-Formatierung mit der hervorgehobenen Variablen verwenden. Wir verwenden standardmäßigyour_domain. wiehttps://your_domain:3000/simple/ oderhttp://your_server_ip/. Live-Links sollten jedoch stattdessen den Standard-Markdown-Linkstil ohne zusätzliche Formatierung verwenden.

Software

Verwenden Sie die Groß- und Kleinschreibung der offiziellen Website für den Namen ihrer Software. Wenn die Produktwebsite nicht mit der Groß- und Kleinschreibung übereinstimmt, müssen Sie nur innerhalb eines Artikels übereinstimmen.

Link zur Homepage der Software, wenn Sie die Software zum ersten Mal erwähnen.

Multi-Server-Setups

Verwenden Sie aus Gründen der technischen Klarheit die Terminologie des Projekts für Multi-Server-Setups. Bitte stellen Sie klar, dass die Bedingungen aus dem Projekt stammen. Zum Beispiel: „Das Django-Projekt bezeichnet den ursprünglichen Server alsprimary und den sekundären Server alsreplica. Das MySQL-Projekt bezeichnet den ursprünglichen Server alsmaster und den sekundären Server alsslave. “

Verwenden Sie die Begriffeprimary undreplica odermanager undworker, wenn Sie Architekturen mit mehreren Servern abstrakter diskutieren.

Technische Best Practices

Unsertechnical best practices guide-Handbuch enthält weitere Anleitungen, mit denen Sie konsistente, qualitativ hochwertige Tutorials erstellen können, die unseren Lesern helfen.

Folgen Sie diesem Link zubecome a DigitalOcean author.

Related