Wie man eine Technologie recherchiert

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:

• Web-Technologien wie HTML, CSS und JavaScript.
• Lesen von Web-Technologie-Spezifikationen. Sie werden sich diese oft anschauen, während Sie APIs dokumentieren.

Alles andere kann im Laufe der Zeit gelernt werden.

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

1. Die Anleitungen für MDN Web Docs: Sie sind bereits hier, aber es ist gut, alle Artikel durchzusehen und sich mit unserem Schreibstil, den verschiedenen Seitentypen und den darin enthaltenen Abschnitten sowie den verschiedenen Möglichkeiten, wie wir verschiedene Teile der Seite einbinden (wie Spezifikationen und Browser-Kompatibilität), vertraut zu machen.
2. Die neueste Spezifikation: Verschiedene Standardisierungsgremien 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 den Referenzseiten von MDN Web Docs verlinkt (sehen Sie im Abschnitt "Spezifikationen" nach). Alternativ können Sie normalerweise auch eine Websuche durchführen. Arbeiten Sie immer mit der neuesten, aktuellsten Spezifikation.
3. Die neuesten modernen Webbrowser: Diese sollten experimentelle/Alpha-Builds sein wie Firefox Nightly, Chrome Canary oder Safari Technology Preview, die die Funktionen, die Sie dokumentieren, eher unterstützen. Dies ist besonders relevant, wenn Sie eine Funktion dokumentieren, die "bevorstehend" ist.
4. Demos/Blogposts/sonstige Informationen: Finden Sie so viele Informationen wie möglich. Wenn Sie eine Technologie aktualisieren, weil sie sich geändert hat, stellen Sie sicher, dass die von Ihnen genutzten Ressourcen nicht veraltet sind. Deshalb sind die ersten beiden Punkte oben wichtig.

Es kann auch klug sein, jemanden zu finden, der Fragen beantworten kann. Dies können die Spezifikationsautoren oder die Ingenieure sein, die Browserfunktionen implementieren.

Dies mag anfangs etwas fremd erscheinen, aber je öfter Sie es tun, desto mehr gewöhnen Sie sich daran. Hier sind einige gute Links, um Ihnen den Einstieg zu erleichtern:

• Wie man W3C-Spezifikationen liest von J. David Eisenberg auf A List Apart
• Verstehen der CSS-Spezifikationen von der W3C
• Wie man Web-Spezifikationen liest Teil I – oder: WebVR, wie funktioniert das? erklärt das Lesen der WebVR-Spezifikation im Speziellen, bietet aber eine großartige Einführung in das Lesen von Web-API-Spezifikationen.
• Wie man Web-Spezifikationen liest Teil IIa – oder: ECMAScript Symbole der zweite Teil des obigen Links enthält Informationen zum Verständnis der ECMAScript-Spezifikation, die die JavaScript-Sprache umrissen.

Zusätzlich haben wir den Informationen in einer WebIDL-Datei Leitfaden, der beim Lesen von Web-API-Spezifikationen wirklich hilfreich sein kann.

Sie werden viele Male im Laufe der Dokumentation einer Technologie auf das Schreiben von Codebeispielen oder das Erstellen von Demos zurückgreifen müssen, 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 dafür vermittelt, was die Anwendungsfälle sind (warum ein Entwickler diese Technologie verwenden würde) und gleichzeitig hilft, einige Codebeispiele zu erstellen.

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, die Sie dokumentieren, an. Wahrscheinlich müssen Sie auch bestehende Dokumentationen aktualisieren, daher sollten Sie auf MDN Web Docs nach Seiten suchen, die sich auf das Thema beziehen, über das Sie schreiben.

Es ist möglich, dass die Seitenleiste der von Ihnen geschriebenen Seiten ebenfalls definiert oder aktualisiert werden muss. Um herauszufinden, ob dies erforderlich ist und wie es gemacht wird, sehen Sie sich den Leitfaden für Seitenleisten an.

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

Der Code-Beispiele Artikel beschreibt die verschiedenen Arten von Code-Beispielen, die wir auf MDN Web Docs verwenden.

Angenommen, Sie dokumentieren eine neue Web-API, Ihre anfängliche Liste von zu dokumentierenden Abschnitten sieht ungefähr so aus:

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

Sie können es dann mit mehr Details erweitern und jedes Interface und seine Mitglieder hinzufügen. Wenn Sie beispielsweise die Web Audio API dokumentieren, könnte Ihre Liste folgendermaßen 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
  • …

An diesem Punkt ist es eine gute Idee, ein Tracking-Issue im mdn/content-Repository mit den als To-Do (Checkbox-)Liste aufgeführten Seiten zu eröffnen. Dies ermöglicht 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 benötigten Seiten. Um eine neue Seite zu erstellen, lesen Sie die Anweisungen in unserem Wie man Seiten erstellt, verschiebt, löscht und bearbeitet Leitfaden. Sehen Sie sich unseren Seitentypen Leitfaden für Seitentemplates an, die nützlich sein könnten.