Diese Seite wurde von der Cloud Translation API übersetzt.
Switch to English

Styleguide für Tutorials

Damit sich Nutzer effektiv mit Ihrem Projekt vertraut machen können, finden Sie hier einige Richtlinien, mit denen Sie Ihre Inhalte am besten in Form einer Anleitung präsentieren können.

Features von Cloud Shell

  • Einzigartiges Layout:Anleitungen werden in der Seitenleiste rechts auf der Google Cloud Console angezeigt.
  • Navigation:Nutzer können in jedem Schritt die Anleitung über die Schaltflächen Weiter und Zurück aufrufen. Sie können die Anleitung auch schließen und dort weitermachen, wo sie aufgehört haben.
  • Zu verwendender Code:Code-Snippets können direkt in Cloud Shell kopiert werden.

Konsolensitzung mit gestarteter Anleitung

Google Cloud Shell Editor-Sitzung mit geöffnetem Anleitungsbereich. Nutzer können Code direkt in Google Cloud Shell kopieren. Mit den Schaltflächen Weiter und Zurück können Sie zwischen Seiten wechseln.

Schreibstil

  • Fassen Sie sich dabei:Anleitungen sollten informativ und nützlich sein, aber nicht zu formell.
  • Sie, der Nutzer:Verwenden Sie Pronomen der zweiten Person (Verwenden Sie: Sie, Ihre; nicht verwenden:,, und so weiter)
  • Erklären Sie die Ursache und den Grund:Wenn Sie die Nutzer bitten, einen Schritt auszuführen, erklären Sie die Gründe für die Maßnahme und das erwartete Ergebnis.
  • Klare Ziele:Bevor Sie den Inhalt für Ihre Anleitung schreiben, sollten Sie ein klar definiertes Ziel definieren, das die Nutzer erreichen sollen. Entwerfen 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 auf Cloud Shell leiten, damit sie schnell mit Ihrem Projekt beginnen, einen Anwendungsfall durchgehen und sich mit der Funktionalität Ihres Projekts vertraut machen können.

    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 zu sehen sind, 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.
    • Hervorhebungen statt Screenshots verwenden: Indem Sie hervorheben, wo sich UI-Elemente in der Console befinden, können Nutzer die Elemente identifizieren, ohne ein Bild absuchen 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

    Zum Schreiben Ihrer Anleitung sollten Sie [Markdown] (https://en.wikipedia.org/wiki/Markdown) verwenden und dabei diese Richtlinien einhalten:

    ### 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!

    Ihre Nutzer können Ihre Anleitung jetzt in Cloud Shell starten und damit ganz einfach in Ihr Projekt einsteigen.

    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>`.