Kriterien für die Aufnahme in MDN Web Docs

Der Auftrag von MDN Web Docs besteht darin, Web-Standards-Technologien zu dokumentieren, die in einer Spezifikation veröffentlicht sind, die von einem zuverlässigen Standardisierungsgremium stammt und in mindestens einem stabilen Browser unterstützt wird. Diese Kriterien signalisieren ein ausreichendes Interesse, Stabilität und die "Absicht zur Implementierung" von der Webindustrie im Allgemeinen. Daher glauben wir, dass diese Technologien sicher genug sind, damit wir unsere Zeit und Mühe darauf verwenden, sie zu dokumentieren. Andernfalls könnte eine Web-Technologie oder ein Feature möglicherweise aufgrund von mangelndem Interesse abgesagt werden oder so instabil sein, dass es sich erheblich ändern könnte, was unnötigerweise viele Umschreibungen erfordern würde (die wir nach Möglichkeit zu vermeiden versuchen).

Nicht-Web-Standards-Technologien sind Technologien, die unseren oben zusammengefassten Kriterien nicht folgen. Normalerweise würden wir sie nicht für die Dokumentation bei MDN Web Docs in Betracht ziehen.

Unsere Mission lautet "Entwicklern die Informationen bereitzustellen, die sie benötigen, um Projekte im offenen Web einfach zu erstellen". Dies deutet darauf hin, dass wir darüber nachdenken sollten, Technologien zu dokumentieren, die für Webentwickler nützlich sind, auch wenn sie keine offenen Webstandards sind, sich nicht auf dem Standardisierungspfad befinden usw.

Wenn Sie in Betracht ziehen, eine Nicht-Web-Standard-Technologie zur Aufnahme in MDN Web Docs vorzuschlagen, sollten Sie sicherstellen, dass sie den untenstehenden Kriterien entspricht.

Technologien sollten die hier beschriebenen Kriterien erfüllen, um in Betracht gezogen zu werden, auf MDN Web Docs dokumentiert zu werden.

Bei MDN Web Docs unterstützen wir offene Technologien. Wir unterstützen keine geschlossenen Technologie-Ökosysteme, die von einem einzigen Unternehmen kontrolliert werden, die nicht für Beiträge von interessierten Parteien offen sind und nicht über mehrere Plattformen und Systeme interoperabel sind. Wir glauben, dass Technologien für alle besser funktionieren, wenn sie offen entwickelt werden.

Unser zentraler Auftrag sind Web-Standards-Technologien; es macht keinen Sinn, mit der Dokumentation von Technologien zu beginnen, die nicht mit dem Web in Zusammenhang stehen oder kein Interesse für Webentwickler haben.

Wir wollen unsere Zeit nicht damit verbringen, eine Technologie zu dokumentieren, die kein Signal von Interesse und Annahme von der Industrie zeigt. Es kann sein, dass es einfach zu früh ist, die Technologie zu dokumentieren, und wir könnten in Betracht ziehen, sie in Zukunft auf MDN Web Docs zu dokumentieren.

In Zusammenhang mit dem obigen Punkt wollen wir auch nicht unsere Zeit damit verbringen, eine Technologie zu dokumentieren, die sich in einem späten Stadium ihres Lebenszyklus befindet und bereits Anzeichen von rückläufigem Interesse zeigt.

Es gibt viele Bibliotheken und Frameworks, die existieren, welche keine Webstandards sind, aber auf Webtechnologien basieren und in der Webindustrie sehr beliebt sind. Wir dokumentieren keine davon, da sie im Allgemeinen alle bereits etablierte Dokumentationsressourcen haben. Mit der offiziellen Ressource eines populären Frameworks zu konkurrieren wäre unklug — das wäre eine Zeitverschwendung und würde wahrscheinlich Entwickler, die die Technologie erlernen wollen, verwirren.

Das Team von MDN Web Docs konzentriert sich darauf, die offene Webplattform zu dokumentieren. Wenn Sie möchten, dass eine Technologie in diesem Bereich für die Dokumentation bei MDN Web Docs in Betracht gezogen wird, brauchen Sie eine Gemeinschaft, die bereit ist, die Dokumentation zu schreiben und sie nach der Fertigstellung zu pflegen. Unser Team stellt in solchen Fällen gerne Leitlinien zur Verfügung, einschließlich Bearbeitungen und Feedback, aber wir haben keine Ressourcen für mehr als das.

Wenn eine Technologie wie ein guter Kandidat dafür aussieht, bei MDN Web Docs dokumentiert zu werden, können Sie eine Diskussion in den GitHub-Community-Diskussionen starten, um die Aufnahme dieser Technologie vorzuschlagen und zu diskutieren. Dieser Abschnitt beschreibt, was der Vorschlag beinhalten sollte.

Technologien werden für die Aufnahme in MDN Web Docs von Fall zu Fall betrachtet. Für eine Berücksichtigung müssen Sie einen Vorschlag einreichen, der mit "Proposal for documenting a new technology on MDN Web Docs" betitelt ist. Wir benötigen die folgenden Informationen von Ihnen im Vorschlag:

• Die Technologie, ihr Hauptzweck/Anwendungsfälle und die Zielgruppe der Entwickler.
• Welche Art von Branchen- oder Community-Buzz gibt es um die Technologie?
  • Nutzen viele Webentwickler sie? Wie sieht die Annahme in der Industrie aus?
  • Wollen oder brauchen viele Webentwickler diese Informationen?
  • Wie groß ist die Zielgruppe für diese Informationen? Unterstützende Statistiken wären hilfreich, wenn Sie welche haben.
• Wie steht die Technologie in Zusammenhang mit Kern-Webtechnologien und Webbrowsern? Nützliche Details sind:
  • Verwendet sie HTML und CSS, gibt aber allgemein nicht an das Web aus?
  • Wird sie in Webbrowsern über ein Polyfill unterstützt?
• Welche Dokumentation oder Ressourcen sind bereits verfügbar, die die Technologie abdecken?
• Wie viel Dokumentation müsste zu MDN Web Docs hinzugefügt werden?
  • Listen Sie die erwartete Anzahl von Leitfäden, Tutorials, Referenzseiten für Elemente/Methoden/Attribute auf usw.
  • Bieten Sie ein grobes Inhaltsverzeichnis.
  • Erwähnen Sie die Art von "fortgeschrittenen" Merkmalen, die Sie für diese Ressource erwarten, über die grundlegenden Dokumentationsseiten hinaus. Erwarten Sie die Einbindung von eingebetteten Videos, interaktiven Codebeispielen usw.?
• Wer wird die Dokumentation schreiben? Wer sind sie und warum sind sie für die Aufgabe geeignet?
• Wie wird die Dokumentation gepflegt?

Sie müssen uns in diesem Stadium nicht hunderte von Seiten mit Details bereitstellen (tatsächlich würden wir es bevorzugen, wenn Sie das nicht tun). Ein paar Absätze zu jedem der oben genannten Punkte reichen mehr als aus.

Wir werden die Technologie und die von Ihnen im Vorschlag eingereichten Informationen prüfen und mit einer der folgenden Antworten antworten:

• Nein: Wir denken, dass dies nicht die Kriterien erfüllt, um bei MDN Web Docs dokumentiert zu werden.
• Vielleicht: Wir sind uns nicht sicher, ob es sich für die Dokumentation bei MDN Web Docs eignet und möchten einige weitere Fragen stellen.
• Ja: Wir denken, dass es angemessen ist, es bei MDN Web Docs aufzunehmen.

Wenn die Technologie ein guter Kandidat ist, wird das Team Ihnen helfen, mit der Dokumentation zu beginnen.

Wenn Ihre gewählte Technologie zur Dokumentation bei MDN Web Docs akzeptiert wird, ist der nächste Schritt, loszulegen.

Um sicherzustellen, dass Ihr Projekt zur Dokumentation der neuen Technologie bei MDN Web Docs erfolgreich ist, benötigen wir Folgendes:

• Ein engagiertes Team
• Einen Projektplan und eine Roadmap
• Leitlinien und Standards für das Schreiben
• Eine intuitive Dokumentationsstruktur
• Einen Wartungsplan

Stellen Sie sicher, dass Sie ein engagiertes Team haben, das sowohl die anfängliche Dokumentation verfasst als auch sie in der Zukunft mit den erforderlichen Aktualisierungen pflegt.

Denken Sie darüber nach, wie viel Arbeit anfällt und wie viele Personen Sie dafür benötigen könnten.

• Wenn es sich um ein großes Projekt handelt, könnten Sie von mehreren Autoren profitieren, einem technischen Prüfer, der die technische Genauigkeit überprüft, einem Lektor, der die Sprache reinigt, jemandem, der Codebeispiele schreibt usw.
• Bei einem kleineren Projekt könnten ein oder zwei Personen mehrere Rollen übernehmen. Wie immer Sie das Team aufbauen möchten, ist in Ordnung, solange es für Sie funktioniert.

Ein Mitglied des MDN Web Docs-Teams wird Ihrem Projekt zugewiesen, um Anleitungen im Hinblick auf MDN Web Docs bereitzustellen.

Sie sollten ein oder zwei Teamleiter ernennen, die mit dem MDN Web Docs-Teammitglied in Kontakt treten können.

Der MDN Web Docs-Vertreter wird helfen, die erforderlichen Berechtigungen für alle Teammitglieder zu erhalten, um in der MDN-Organisation auf GitHub zu arbeiten.

Erstellen Sie einen Plan für das Projekt — Aufgaben, geschätzte Fertigstellungstermine und Meilensteine, die Sie verfolgen möchten, um sicherzustellen, dass Sie stetige Fortschritte machen.

Wenn das Projekt groß ist, sollten Sie in Betracht ziehen, eines Ihrer Teammitglieder als Projektmanager zu ernennen. Sie sollten auch in Erwägung ziehen, einen Teilprojektplan für eine erste Veröffentlichung zu schreiben, der das Mindestmaß an Dokumentation umfasst, das nützlich ist zu veröffentlichen (ein Minimum Viable Product); Sie können später weitere Ergänzungen vornehmen.

Wenn das Dokumentationsprojekt klein ist, müssten Sie dennoch ein Protokoll darüber führen, was getan wurde und was nicht, in welchem Stadium sich jeder Teil der Dokumentation befindet (z.B. nicht begonnen, in Bearbeitung, Entwurf geschrieben, geprüft, fertig), und wer an was arbeitet.

Diese Leitlinien geben an, wie wir erwarten, dass Dokumente für MDN Web Docs geschrieben werden.

Wenn Sie zusätzliche Leitlinien für die Dokumente haben, die Sie schreiben, erwarten wir, dass diese Anleitung hinzugefügt und auf dem neuesten Stand gehalten wird.

Was die Standards betrifft, erwarten wir, dass Sie ein angemessenes Maß an Schreibqualität für Ihre Dokumentation beibehalten, damit sie auf MDN Web Docs bleibt. Ihr MDN Web Docs-Vertreter wird mit Ihnen zusammenarbeiten, um Ihnen klar zu machen, was erwartet wird.

Wenn Sie den Prozess der Vorschlagseinreichung durchlaufen haben, sollten Sie bereits eine grobe Übersicht darüber haben, was Sie für diese Technologie schreiben werden. An diesem Punkt sollten Sie das in einen Plan für die Seitenstruktur verfeinern: Überlegen Sie, wie die Dokumenthierarchie aussehen wird und wo alles passt und miteinander verlinkt ist.

Jedes Projekt ist anders, aber wir empfehlen den folgenden Verzeichnisbaum:

├── Guides
│   ├── guide_one
│   ├── guide_two
│   └── index.md
├── index.md
├── Reference
│   ├── Elements
│   ├── Methods
│   ├── Others ?
│   └── index.md
└── Tutorials
    ├── tutorial_one
    ├── tutorial_two
    └── index.md

Jeder Seitentyp, den Sie in Ihrem Projekt verwenden werden, sollte eine Seitenschablone haben, von der andere die Struktur kopieren können. Sie sollten sich frühzeitig darauf festlegen.

Bitte sehen Sie sich unseren Abschnitt zu Seitentypen an. Wenn Ergänzungen erforderlich sind, setzen Sie sich bitte mit Ihrem MDN Web Docs-Vertreter in Verbindung.

Die Dokumentation für diese Technologie muss gepflegt werden, um auf MDN Web Docs zu bleiben:

• Der Inhalt und die Dateien für MDN Web Docs werden auf GitHub gespeichert. Wenn andere Änderungen an der Dokumentation für Ihre Technologie vornehmen, muss ein Mitglied Ihres Teams diese Änderungen überprüfen, um sicherzustellen, dass der Inhalt weiterhin gut ist. Sie können die offenen Pull Requests (PRs) über GitHubs Benachrichtigungsfunktion verfolgen.
• Wenn sich an der Technologie Änderungen ergeben, die eine Aktualisierung der Dokumentation erfordern, muss Ihr Team entsprechende Aktualisierungen vornehmen und die gleichen Standards wie die ursprüngliche Dokumentation beibehalten.

Wenn innerhalb eines Zeitraums von sechs Monaten keine positiven Änderungen beobachtet werden und die Dokumentation in einem der folgenden Zustände erscheint:

• Veraltet oder ungepflegt
• Ins Stocken geraten, ohne abgeschlossen zu werden
• Niedrige Qualität
• Veraltet werden

Dann wird die Dokumentation für diese Technologie als tot betrachtet. Nach einer Diskussion zwischen Ihrem Team und dem MDN Web Docs-Teamvertreter wird die Dokumentation entfernt.

Wir hoffen, dass Sie verstehen, dass wir in solchen Angelegenheiten strikt sein müssen — wir können nicht zulassen, dass die Seite mit schlechter Qualität, unvollständiger oder veralteter Dokumentation gefüllt wird.