Inhaltsverzeichnis

Dokumentationsarten

Es folgt eine kurze Übersicht über die Arten von Dokumentationsbeiträgen, die bei amp.dev akzeptiert werden:

Einführungstutorial

Einführungstutorials vermitteln Entwicklern ein allgemeines Bild der Technologie. Sie beginnen mit dem Schreiben von Code und enden mit einem kompletten "Hallo Welt" Basisprojekt. Einführende Tutorials zeigen Schritt für Schritt, wie man die jeweilige AMP Kernfunktion erstellt. Du kannst Einführungstutorials kombinieren mit Inline Codebeispielen und/oder einem herunterladbaren Beispiel, das Entwickler schon nach minimalen Änderungen nutzen können.

Beispiele für amp.dev:

Richtig	Falsch
Gib mit kurzen Erklärungen und möglichst wenig Schritten eine Orientierungshilfe.	Tauche nicht tief in alle Nuancen des Projekts ein. Es gibt viele Wege, den Inhalt des Tutorials effektiv zu vermitteln. Aber anstatt alle möglichen Routen aufzuzeigen, solltest du dich auf eine einzige, gute Route fokussieren.
Stelle eine vereinfachte Umgebung und Setup Tools bereit.	Setze nicht voraus, dass die Entwickler das Produkt kennen und auf professionellem Level programmieren können.
Vereinfache Beispiele visuell.	Verzichte auf eine komplexe Darstellung für einen anspruchsvollen Stil. Ausnahme: Im Tutorial geht es um Styling.
Stelle Screenshots für die einzelnen Schritte und ein fertiges Demo bereit.	Stelle nicht nur Codebeispiele bereit.
Fordere zum Handeln auf. Weise Entwickler auf weiterführendes Material hin.	Kombiniere das Beispiel nicht mit weiterführenden Erklärungen. Erstelle besser ein Issue für einen Leitfaden oder ein Tutorial, wenn deiner Meinung nach weiterführende Inhalte fehlen.

Tutorial für Fortgeschrittene

Tutorials für Fortgeschrittene helfen Entwicklern, eine bestimmte Aufgabe zu erfüllen. Das setzt voraus, dass die Entwickler mit AMP vertraut sind. Das Tutorial soll demonstrieren, wie man eine Erfahrung schaffen, eine Funktion integrieren oder Implementierungsaufgaben erledigen kann.

Beispiele für amp.dev:

Richtig	Falsch
Stelle Schritt-für-Schritt Anweisungen mit einem klaren Zielprojekt bereit.	Stelle keine erschöpfenden Details und überladenen Konzepte bereit.
Stelle Codebeispiele oder herunterladbaren Basiscode bereit. Biete das endgültige und vollständige Projekt als zusätzlichen Download an.	Stelle keine alternativen Beispiele oder Verfahren bereit, um das Endergebnis zu erreichen.
Erstelle eine Plug and Play Umgebung.	Verweise nicht einfach auf ein externes Setup Tutorial. Tutorials sollten in sich abgeschlossen sein.

Einführungsleitfaden

Ein Einführungsleitfaden bietet einen Überblick über relevante Informationen für die ersten Schritte mit AMP. Er sollte das Feature identifizieren, seine Eigenschaften beschreiben und seine Funktionen erklären. Einführungsleitfäden stellen Entwicklern die Grundvoraussetzungen des Features vor, ohne auf die Implementierung einzugehen. Wenn du einen Prozess Schritt für Schritt mit Codebeispielen durchgehst, verfasst du wahrscheinlich ein Tutorial. Wenn du einen Überblick über alle programmgesteuerten Elemente für eine AMP Komponente gibst, schreibst du wahrscheinlich ein Referenzdokument.

Beispiele für amp.dev:

Richtig	Falsch
Definiere klar den thematischen Umfang des Dokuments.	Stelle den Prozess nicht in Einzelschritten dar.
Stelle Features und Konzepte vor. Verweise auf Referenzdokumente, die Details zur Verwendung bieten.	Beschreibe keine unnötigen Details.
Stelle Codebeispiele und praktische Beispiele bereit.	Erstelle nicht eine ganze App. Verweise auf Beispiele oder Demos, anstatt weiterführende Informationen anzubieten.
Nenne technische Anwendungsmöglichkeiten und Einschränkungen.	Zähle nicht alle denkbaren technischen Verwendungsmöglichkeiten auf und gehe nicht auf ihre Implementierung ein.

Konzeptleitfaden

Mithilfe von Konzeptleitfäden können Entwickler ein tieferes Verständnis von AMP aufbauen. Ein Konzeptleitfaden ist wie eine topografische Karte. Er zeigt die verschiedenen Pfade einer Umgebung und bietet Details wie z. B. Höhenangaben, schreibt dabei aber keine bestimmte Route durch das Gelände vor. Erkläre, was das Feature ist und wie es funktioniert, ohne darauf einzugehen, wie das Feature erstellt wird.

Beispiele für amp.dev:

Richtig	Falsch
Stelle den Entwicklern alle Elemente zur Verfügung, die zum Erstellen einer Lösung benötigt werden.	Führe die Entwickler nicht aktiv zu einem vorbestimmten Ziel.
Decke alle Aspekte der Themenbereiche ab.	Konzentriere dich nicht auf eine bestimmte Aufgabe.
Füge visuelle Hilfsmittel wie Diagramme oder Screenshots hinzu.	Denke nicht unnötig lange darüber nach. Bei Bedarf kannst du bei der [Outreach Arbeitsgruppe](https://github.com/ampproject/wg-outreach) Unterstützung für visuelle Hilfsmittel anfordern.
Stelle Codebeispiele bereit und setze Links zu anderen Leitfäden.	Biete nicht einen Download zu einem fertigen Projekt an und schweife nicht vom Thema ab.

Referenzdokumentation

Eine Referenzdokumentation enthält alle programmatischen Elemente einer AMP Komponente. Sie bietet präzise Informationen zu deren Verhalten und soll überflogen werden können. Die Referenzdokumentation sollte exemplarische Codebeispiele enthalten und Use Cases präsentieren.

Referenzdokumente für amp.dev findest du unter AMP Komponentenkatalog.

Die AMP Referenzdokumentation wird zum AMPHTML Repository beigetragen.

Richtig	Falsch
Erkläre klar und präzise, wie die Komponente funktioniert.	Erkläre keinen Prozess, erstelle kein Projekt.
Strukturiere mit leicht verständlichen Titeln, Überschriften und Unterüberschriften.	Gruppiere Inhalte nicht unter abstrakten Namen.
Stelle Code Snippets bereit, um die Verwendung der Komponente zu demonstrieren.	Erstelle keine vollständigen Demoanwendungen.

Written by @CrystalOnScript