Die folgenden Richtlinien helfen Ihnen dabei, Ihre Inhalte in Anleitungsform darzustellen, damit sich Ihre Nutzer effektiv mit Ihrem Projekt vertraut machen können.
Features von Cloud Shell
- Einzigartiges Layout:Anleitungen werden in einer Seitenleiste auf der rechten Seite der Google Cloud Console angezeigt.
- Navigation: Nutzer können sich in jedem Schritt mithilfe der Schaltflächen Weiter und Zurück durch die Anleitung bewegen. Sie können die Anleitung auch schließen und an der Stelle fortfahren, an der sie aufgehört haben.
- Code to go: Code-Snippets können direkt in Cloud Shell kopiert werden.
Eine Cloud Shell-Editor-Sitzung mit geöffnetem Anleitungsbereich. Nutzer können Code direkt in Cloud Shell kopieren, indem sie auf eine Schaltfläche klicken, und mit den Schaltflächen Weiter und Zurück zwischen den Seiten wechseln.
Schreibstil
- Lockerer Umgangston: Schritt-für-Schritt-Anleitungen sollten informativ und hilfreich sein, aber nicht übermäßig formell.
- Anrede des Nutzers in der zweiten Person:Verwenden Sie Pronomen der zweiten Person (Verwenden Sie: Sie, Ihre; Verwenden Sie nicht: Wir, ich, unser usw.)
- Ursache und Wirkung erläutern: Wenn Sie die Nutzer dazu auffordern, einen Schritt auszuführen, erklären Sie die Gründe für die Aktion und das erwartete Ergebnis.
- Klare Ziele: Bevor Sie den Inhalt für Ihre Anleitung schreiben, legen Sie ein klar definiertes Ziel fest, das Ihre Nutzer erreichen sollen. Gestalten Sie Ihre Anleitung unter Berücksichtigung dieses Ziels.
| Original | Überarbeitet | Verbesserung |
| Auf der nächsten Seite erfahren Sie, wie Sie eine neue Anleitung erstellen. | Im nächsten Schritt beginnen Sie mit der Einrichtung Ihrer Anleitung. | Auf den Nutzer konzentrieren; aktive Verbform verwenden
Informelle Sprache verwenden |
| Führen Sie folgenden Befehl aus:
``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` |
Führen Sie den folgenden Befehl aus, um eine tabellarische Liste aller Ihrer Projekte und ihrer ID-Nummern mit dem Titel "Projects" anzuzeigen: ``` gcloud projects list --format="table[box,title=Projects](name, projectId)" ``` | Herangehensweise im Voraus begründen, um die Erwartungen an das Ergebnis festzulegen |
Let's get started!
|
Let's get started!
In diesem Leitfaden erfahren Sie, wie Sie eine eigene interaktive Anleitung erstellen. Sie werden auch Schritt für Schritt durch die Erstellung einer Schaltfläche geführt, mit der die Nutzer die fertige Anleitung starten können. |
Fassen Sie die in der Anleitung behandelten Lektionen klar und deutlich zusammen.
Achten Sie beim Schreiben von Inhalten darauf, diesen Fokus beizubehalten! |
Best Practices
Fassen Sie sich kurz: Die Anleitung unterliegt spezifischen Platzbeschränkungen, weshalb einem Nutzer jeweils nur eine begrenzte Menge an Informationen angezeigt werden können. Vermeiden Sie große Textblöcke, die schwer zu lesen sind und vertikales Scrollen erfordern; gliedern Sie stattdessen Informationen in übersichtlichen Sinneinheiten.
Schreiben Sie wenn möglich nicht mehr als fünf Schritte und drei Code-Snippets pro Seite.
Absätze sollten im Idealfall fünf Zeilen oder weniger umfassen und sich auf ein einzelnes Konzept beziehen.
Wenn eine Seite länger sein muss, sollte sie maximal doppelt so lang wie das Fenster sein.
Code- und Terminalblöcke sollten so übersichtlich sein, dass man sie gut lesen kann:
- Streben Sie zehn Zeilen oder weniger an.
- Beschränken Sie sich pro Zeile möglichst auf höchstens 80 Zeichen, um den horizontalen Bildlauf zu reduzieren.
- Vermeiden Sie Codeblöcke mit mehreren Befehlen, damit Nutzer nicht mehrere Befehle gleichzeitig kopieren und ausführen müssen.
Einführungsseite: Beginnen Sie Ihre Anleitung mit einer Einführung.
- Erwartungen festlegen: Erklären Sie kurz, wie Ihre Nutzer vom Durchführen dieser Anleitung profitieren.
- Geschätzter Zeitaufwand: Schätzen Sie ungefähr ein, wie lange Nutzer voraussichtlich für die Anleitung brauchen werden. Erstellen Sie eine Anleitung, die in weniger als 15 Minuten abgeschlossen werden kann. Wenn sie länger ist (oder aus mehr als 15 eng beschriebenen Seiten besteht), sollte sie in mehrere kürzere Anleitungen aufgeteilt werden.
- Voraussetzungen zu Beginn nennen: Geben Sie alle erforderlichen Ressourcen oder Zugriffsrechte an, die der Nutzer benötigt, um die Anleitung unterbrechungsfrei auszuführen.
Beispiel ## Los gehts!
Verschaffen Sie Ihren Nutzern mit einer interaktiven Anleitung einen schnellen Einstieg in Ihr Projekt.
In diesem Leitfaden wird gezeigt, wie Sie eine eigene interaktive Anleitung (wie diese hier) erstellen können. Sie werden auch Schritt für Schritt durch die Erstellung einer Schaltfläche geführt, mit der die Nutzer die fertige Anleitung starten können.
**Zeit zum Durcharbeiten**: etwa 10 Minuten
**Voraussetzungen**: Ein Cloud-Rechnungskonto
Mit einem Klick auf die Schaltfläche **Weiter** gelangen Sie zum nächsten Schritt.
Hintergrundseite
- Überblick bieten: Es ist oft hilfreich, eine Anleitung mit Kontext zu versehen. Das kann bedeuten, dass Sie einen kurzen Überblick über das Produkt geben oder die wichtigsten Funktionen einer UI schnell durchgehen.
Beispiel ## Was ist Cloud Shell?
Bevor Sie anfangen, gehen wir kurz auf die Möglichkeiten von Cloud Shell ein.
Cloud Shell ist eine persönliche, gehostete virtuelle Maschine mit vorinstallierten Entwicklertools für Google Cloud-Produkte. Diese interaktive Shell-Umgebung enthält einen integrierten Codeeditor, nichtflüchtigen Festplattenspeicher und eine Webvorschaufunktion. Wenn Sie nur mit der Befehlszeile arbeiten möchten, verwenden Sie [console.cloud.google.com/cloudshell](https://console.cloud.google.com/cloudshell).
Sie können Ihre Nutzer zu Cloud Shell leiten, um ihnen einen schnellen Einstieg in Ihr Projekt zu ermöglichen. Geben Sie ihnen die Möglichkeit, einen Anwendungsfall durchzugehen und sich mit der Funktionalität Ihres Projekts vertraut zu machen.
Im nächsten Schritt beginnen Sie mit der Einrichtung Ihrer Anleitung.
Einfache Beispiele:
- Hallo Welt: Das erste Beispiel, das Sie bereitstellen, sollte so einfach sein, dass Sie es ohne viel Erklärung testen können. Es sollte Ihr Äquivalent zu "Hallo Welt" sein. Verwenden Sie dieses Beispiel als Basis, auf die weitere Konzepte aufbauen, die in der Anleitung veranschaulicht werden.
Beispiel ## Anleitungen im Kontext
Was Sie gerade sehen, ist eine Anleitung im Kontext.
Die Inhalte werden zusammen mit der Cloud Shell-Umgebung angezeigt, in der Sie die Anleitungsschritte ausführen können. Da Anleitung und Entwicklungsumgebung an derselben Stelle erscheinen, können Nutzer mit einem normalen Einzelbildschirm das Projekt so leichter nachvollziehen.
Versuchen Sie jetzt, einen Befehl auszuführen:
```bash
echo "Hallo Cloud Shell"
```
**Tipp**: Klicken Sie neben dem Codefeld auf „Kopieren“, um den Befehl im Cloud Shell-Terminal einzufügen und auszuführen.
Im nächsten Schritt schreiben Sie eine einfache Anleitung und starten diese.
Inhalt der Anleitung
- Durchdachte Formatierungen: Textformatierungen (fett, kursiv usw.) lenken ab. Verwenden Sie diese nur bei Bedarf und zu Ihrem Vorteil (für Warnungen, zentrale Fakten usw.).
- Konsistente Grammatik: Verwenden Sie beim Beschreiben von Nutzeraktionen die Imperativform und achten Sie darauf, dass Sätze mit einem Punkt beendet werden.
- Verweise auf Links: Fügen Sie, sofern dies für den Kontext wichtig ist, ergänzende Links ([Linktext](Link-URL)) hinzu, damit Nutzer selbst nachschlagen können.
- Hervorhebung statt Screenshots verwenden:Mit Spotlighting wird hervorgehoben, wo sich die UI-Elemente in der Google Cloud Console befinden. So lässt sich die Position so darstellen, dass Nutzer Elemente identifizieren können, ohne ein Bild durchsuchen zu müssen.
- Alternative Ansicht: Falls möglich geben Sie einen Link zu Ihrem Anleitungsinhalt an, der als statischer Inhalt angeboten wird. Auf diese Weise kann der Nutzer selber wählen, wie er die bereitgestellten Informationen konsumieren möchte.
- Tipps sind empfehlenswert: Fügen Sie gegebenenfalls Tipps hinzu („**Tipp:**“), um den Nutzern intuitivere Lösungen und Best Practices zu bieten.
Beispiel ## In Markdown schreiben
Verwenden Sie zum Schreiben Ihres Tutorials [Markdown](https://en.wikipedia.org/wiki/Markdown) und beachten Sie die folgenden Richtlinien:
### Titel bearbeiten
Ändern Sie den Titel dieser Anleitung („# Einführung in das Schreiben von Anleitungen in Cloud Shell“) folgendermaßen ab:
```
# So lerne ich, eine Anleitung zu schreiben
```
### Einen neuen Schritt hinzufügen
Nun fügen Sie direkt nach dem Titel einen weiteren Schritt ein:
```
## Schritt 1
Dies ist ein neuer Schritt, den ich gerade hinzugefügt habe.
```
Jeder 'Schritt' einer Anleitung wird auf einer eigenen Seite angezeigt.
**Tipp**: Verwenden Sie die Schaltflächen „Zurück“ und „Weiter/Vorwärts“, um die einzelnen Schritte durchzugehen.
Zusammenfassung
- Glückwunsch: Denken Sie daran, ein Trophäensymbol (<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>) hinzuzufügen, um den Nutzern dafür zu danken, dass sie sich die Zeit für die Anleitung genommen haben.
- Zusammenfassung: Fassen Sie wichtige Lektionen zusammen, die die Nutzer der Anleitung entnehmen sollten.
- Nächste Schritte: Helfen Sie den Nutzern auf ihrem weiteren Weg, indem Sie die nächsten Schritte nennen – das können Leseempfehlungen, zusätzliche Ressourcen oder sogar eine andere Anleitung sein.
- Nutzer unterstützen: Bitten Sie sie, alle Testressourcen, die sie für die Zwecke der Anleitung erstellt haben, zu bereinigen, um unerwünschte Rechnungsgebühren zu vermeiden.
Beispiel ## Glückwunsch!
<walkthrough-conclusion-trophy></walkthrough-conclusion-trophy>
Fertig!
Sie können jetzt Ihre Nutzer dazu auffordern, Ihre Anleitung in Cloud Shell zu starten, damit sie Ihr Projekt ganz einfach verwenden können.
Eine vollständige Liste der Schreibtools für Cloud Shell-Anleitungen finden Sie in der [Markdown-Referenz für Anleitungen](https://cloud.google.com/shell/docs/tutorial-markdown-reference).
**Denken Sie daran, eigene Projekte zu bereinigen**: Wenn Sie Testprojekte erstellt haben, löschen Sie diese jetzt, um unnötige Kosten zu vermeiden. Verwenden Sie `gcloud projects delete <PROJECT-ID>`.