Anleitung zur Recherche einer Technologie

Bevor Sie beginnen, etwas auf MDN Web Docs zu dokumentieren oder zu aktualisieren, sollten Sie einige Dinge vorbereiten und planen, bevor Sie tatsächlich mit dem Schreiben beginnen.

Es wird angenommen, dass Sie vor dem Lesen dieses Leitfadens ein angemessenes Wissen über Folgendes haben:

• Webtechnologien wie HTML, CSS und JavaScript.
• Das Lesen von Webtechnologie-Spezifikationen. Sie werden diese häufig betrachten, während Sie APIs dokumentieren.

Alles Weitere kann im Laufe der Zeit erlernt werden.

Nützliche Ressourcen für das Schreiben jeglicher Dokumentation beinhalten:

1. Die Anleitungen für MDN Web Docs: Sie sind bereits hier, aber es ist gut, alle Artikel zu durchsuchen und sich mit unserem Schreibstil, den verschiedenen Seitentypen und den enthaltenen Abschnitten sowie den verschiedenen Möglichkeiten, wie wir unterschiedliche Teile der Seite einbeziehen (wie Spezifikationen und Browser-Kompatibilität), vertraut zu machen.
2. Die neueste Spezifikation: Verschiedene Standardisierungsorganisationen erstellen Spezifikationen für Technologien, die auf MDN Web Docs dokumentiert sind. Zum Beispiel TC39 für JavaScript, die WHATWG für HTML und die W3C für CSS, XML und einige Web-APIs. Spezifikationen sind auf Referenzseiten auf MDN Web Docs verlinkt (prüfen Sie den Abschnitt "Spezifikationen"). Alternativ können Sie normalerweise eine Websuche durchführen. Arbeiten Sie immer mit der neuesten, aktuellsten Spezifikation.
3. Die neuesten modernen Webbrowser: Diese sollten experimentelle/Alpha-Versionen wie Firefox Nightly, Chrome Canary oder Safari Technology Preview sein, die eher die Funktionen unterstützen, die Sie dokumentieren. Dies ist besonders relevant, wenn Sie eine Funktion dokumentieren, die "bevorstehend" ist.
4. Demos/Blog-Beiträge/weitere Informationen: Finden Sie so viele Informationen wie möglich. Wenn Sie eine Technologie aktualisieren, weil sie sich verändert hat, stellen Sie sicher, dass die Ressourcen, die Sie verwenden, um zu lernen, nicht veraltet sind. Dies ist der Grund, warum die ersten beiden Punkte oben wichtig sind.

Es kann auch klug sein, jemanden zu finden, der Ihnen bei Fragen helfen kann. Dies können die Autoren der Spezifikation oder die Ingenieure sein, die Browserfunktionen implementieren.

Das kann sich anfangs etwas ungewohnt anfühlen, aber je mehr Sie es tun, desto mehr gewöhnen Sie sich daran. Hier sind einige gute Links, um Ihnen den Einstieg zu erleichtern:

• How to read W3C specs von J. David Eisenberg auf A List Apart.
• Understanding the CSS specifications von der W3C.
• How to read web specs part I – or: WebVR, how do you work? behandelt speziell das Lesen der WebVR-Spezifikation, ist aber eine großartige Einführung in das Lesen von Web-API-Spezifikationen.
• How to read web specs part IIa – or: ECMAScript Symbols der zweite Teil des obenstehenden Links enthält Informationen zum Verständnis der ECMAScript-Spezifikation, die die JavaScript-Sprache umreißt.

Zusätzlich haben wir den Information enthalten in einer WebIDL-Datei Leitfaden, der wirklich helfen kann, wenn Sie Web-API-Spezifikationen lesen.

Sie werden im Laufe der Dokumentation einer Technologie immer wieder zu Codebeispielen zurückkehren oder Demos erstellen, aber es ist sehr nützlich, damit zu beginnen, sich mit der Funktionsweise der Technologie vertraut zu machen. Dies ist eine wirklich wertvolle Übung, da sie Ihnen ein gutes Verständnis der Anwendungsfälle (warum ein Entwickler diese Technologie verwenden würde) und gleichzeitig bei der Erstellung einiger Codebeispiele gibt.

Die verschiedenen Seiten, die Sie von Grund auf neu schreiben oder aktualisieren müssen, variieren je nach der Technologie, über die Sie schreiben. Sehen Sie sich die Seitentypen und den relevanten Abschnitt für die Technologie an, die Sie dokumentieren. Sie müssen höchstwahrscheinlich auch die bestehende Dokumentation aktualisieren, also durchsuchen Sie die MDN Web Docs nach Seiten, die mit dem, worüber Sie schreiben, in Zusammenhang stehen.

Es ist möglich, dass die Seitenleiste der Seiten, die Sie schreiben, ebenfalls definiert oder aktualisiert werden muss. Um herauszufinden, ob dies notwendig ist und wie Sie es tun können, schauen Sie in den Seitenleisten-Leitfaden.

Einige der Codebeispiele für MDN Web Docs befinden sich in separaten Repositories. Am bemerkenswertesten sind dies die interaktiven Beispiele, die im "Probiere es"-Abschnitt auf den Referenzseiten erscheinen, und der größere Democode, der für Leitfäden benötigt wird. Wenn Sie eines dieser Repositories hinzufügen oder ändern müssen, ist es eine gute Idee, dies in Ihrer Liste zu notieren.

Der Codebeispiele Artikel beschreibt die verschiedenen Arten von Codebeispielen, die wir auf MDN Web Docs verwenden.

Angenommen, Sie dokumentieren eine neue Web-API, Ihre anfängliche Liste von zu dokumentierenden Abschnitten könnte folgendermaßen aussehen:

1. Überblicksseite
2. Schnittstellenseiten
3. Konstruktorseiten
4. Methodenseiten
5. Eigenschaftsseiten
6. Ereignisseiten
7. Konzept-/Leitfaden-Seiten
8. Codebeispiele
9. Seitenleisten

Sie können diese Liste dann mit mehr Details erweitern, indem Sie jede Schnittstelle und ihre Mitglieder hinzufügen. Wenn Sie zum Beispiel die Web Audio API dokumentieren würden, könnte Ihre Liste eher so aussehen:

• Web_Audio_API

• AudioContext

  • AudioContext.currentTime
  • AudioContext.destination
  • AudioContext.listener
  • ...
  • AudioContext.createBuffer()
  • AudioContext.createBufferSource()
  • ...

• AudioNode

  • AudioNode.context
  • AudioNode.numberOfInputs
  • AudioNode.numberOfOutputs
  • ...
  • AudioNode.connect(Param)
  • ...

• AudioParam

• Ereignisse (Liste aktualisieren)

  • start
  • end
  • …

Es ist eine gute Idee, an diesem Punkt ein Issue im mdn/content Repository zu eröffnen, mit den Seiten, die als Aufgabenliste (Checkboxen) aufgelistet sind. Dies ermöglicht es nicht nur Ihnen, sondern auch anderen, die an der Dokumentation arbeiten, den Status öffentlich zu verfolgen. Sie können auch Ihre Pull-Requests mit diesem Issue verlinken, um allen mehr Kontext zu geben.

Erstellen Sie nun die Seiten, die Sie benötigen. Um eine neue Seite zu erstellen, sehen Sie sich die Anleitungen in unserem Wie man Seiten erstellt, verschiebt, löscht und bearbeitet Leitfaden an. Schauen Sie sich unseren Seitentypen Leitfaden für Seitentemplates an, die nützlich sein können.