Diese Seite wurde von der Cloud Translation API übersetzt.

ESLint-Projekt

Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison von Google Docs akzeptiert wurde.

Projektzusammenfassung

Open-Source-Organisation:: ESLint
Technischer Redakteur:: Khawar
Projektname:: Konfigurationsdokumentation neu organisieren/umschreiben
Projektdauer:: Standarddauer (3 Monate)

Projektbeschreibung

Zusammenfassung

Ziel dieses Projekts ist es, die Konfigurationsdokumentation für ESLint umzustrukturieren und eine effektive Informationsarchitektur zu schaffen. Dies erleichtert die Navigation und verbessert auch die Nutzbarkeit und Nützlichkeit der Dokumentation.

Projektzusammenfassung Die Konfigurationsdokumentation von ESLint (https://eslint.org/docs/user-guide/Überprüfung) bietet im aktuellen Zustand viele Informationen auf einer einzigen Seite. Trotz der Vorhandensein von Überschriften, Zwischenüberschriften und angemessenen Absätzen auf der Seite kann die Dokumentation überwältigend sein. Es gibt keine Möglichkeit, zu einem bestimmten Abschnitt der Seite zu navigieren, was für einen Nutzer, der sich für einen bestimmten Bereich interessiert, frustrierend ist. Die Informationen können aufgrund dieser mangelnden Organisation auch verloren gehen, da sie nicht ihren Zweck erfüllen und die Nutzenden zu zusätzlichem Anstrengungen auffordern.

Diese Probleme lassen sich jedoch durch eine Reihe sorgfältiger Schritte beheben. Ich schlage vor, bei dieser Umstrukturierung eine Inhaltsprüfung als ersten Schritt durchzuführen. Eine Inhaltsüberprüfung hilft nicht nur bei der Identifizierung von Problemen in der Präsentation der Informationen, sondern hebt auch die Mängel der Inhalte selbst (z.B. veraltete oder unvollständige Informationen) hervor. Anschließend plane ich die Erstellung der Informationsarchitektur (IA), um das Wissensnetzwerk zu enthüllen. So können wir die Informationen nach verschiedenen Themen gruppieren und Verbindungen zwischen verschiedenen eng verwandten Themen finden. Die durch diese beiden Vorgehensweisen gewonnenen Erkenntnisse werden dann verwendet, um die einseitige Dokumentation in mehrere Seiten aufzuteilen. Das gesamte Paket kann dann in Markdown verknüpft und verlinkt werden. Daraus ergibt sich eine besser strukturierte Version der Konfigurationsdokumentation, die leichter zu navigieren und zu verstehen ist.

Motivation Trotz der Tatsache, dass ich bereits seit einiger Zeit Open-Source-Software verwende, ist meine Kenntnis des Begriffs recht neu, ähnlich meinen Kenntnissen über Linting-Software. Als ich anfing, Python (über edX) zu lernen, fragte ich mich, wie winzige Fehler den gesamten Code durcheinanderbringen können. Ich dachte, es wäre schön, Ihre Codes irgendwie testen und Ihre Fehler identifizieren zu können. Dann entdeckte ich den Begriff „Linting“. Ich habe noch keine geeignete Linting-Software verwendet, aber ich bin mir sicher, dass diese mir das Leben in den kommenden Tagen erheblich erleichtern werden.

Mit meinem Hintergrund in Elektrotechnik und einiger Erfahrung im Programmieren kann ich die Probleme des Programmierens und die Anforderungen von Programmierern besser verstehen. Außerdem macht mein Abschluss in den Bereichen Technik und Professionelle Kommunikation mich zu einem Verfechter der Nutzenden und versucht, den Menschen das Leben zu erleichtern. Meine Fähigkeiten und mein Fachwissen werden für dieses Projekt eine gute Kombination sein und einen Mehrwert für die ESLint-Dokumentation bieten.

Ziele Das übergeordnete Ziel dieses Projekts ist es, sicherzustellen, dass die Dokumentation auf der Konfigurationsseite von ESLint leicht verständlich ist und die Nutzer nicht überfordert. Für den Erfolg des Projekts ist es wichtig, dass die Navigation durch die Inhalte einfach und frei von Komplikationen ist. Die wichtigsten Ziele des Projekts sind die folgenden. - Umfassende Inhaltsprüfung durchführen - Informationsarchitektur erstellen, um den Informationsfluss besser zu verstehen - Informationsarchitektur zu verbessern, um die Dokumentation neu zu organisieren - Links und Verweise zwischen verschiedenen Inhaltsabschnitten zu identifizieren - Teile der Dokumentation umzuschreiben bzw. zu bearbeiten, wenn nötig, um die Anforderungen für die Neukonfiguration zu erfüllen

- Achten Sie darauf, dass die Inhalte flexibel und wiederverwendbar sind.

Projektbeschreibung Die Konfiguration von ESLint ist eine wichtige Funktion, durch die ESLint anpassbar ist. An der Konfiguration interessierte Nutzer sind höchstwahrscheinlich an einem oder zwei Aspekten zu einem bestimmten Zeitpunkt interessiert. Daher ist es wichtig, dass Nutzende zu ihrem speziellen Thema geleitet werden, damit sie die Lösung auf effiziente Weise erhalten. Die aktuelle Konfigurationsdokumentation für ESLint enthält viele nützliche Informationen, ist aber so strukturiert, dass sich die Nutzer überfordert, frustriert und verloren fühlen können. Wenn jemand beispielsweise mehr über die Verwendung von Plug-ins von Drittanbietern in ESLint erfahren möchte, muss er nach unten scrollen, um die Diskussion zur Angabe von Parser, Umgebungen und globalen Werten zu lesen. Die ganze Praxis ist ermüdend für die Nutzenden und kann sie von der Website abschrecken. Auch wenn sich ein Nutzer irgendwo in der Mitte der Seite befindet und einen bestimmten Abschnitt aufrufen oder sich nur ähnliche Themen ansehen möchte, ist dies keine leichte Aufgabe für ihn, da ihm keine solche Hilfe zur Verfügung gestellt wird. Diese Probleme müssen sofort behoben werden, da die Qualität einer Dokumentation unabhängig von ihrem Entwurf von ihrem Nutzen abhängt. In der folgenden Diskussion schlage ich Lösungen für diese und andere damit verbundene Probleme vor.

Inhaltsprüfung Der erste Schritt bei der Neuorganisation der Konfigurationsdokumentation wäre eine umfassende Inhaltsprüfung. Ziel der Prüfung ist es, einige zentrale Probleme wie veraltete Inhalte, Duplikate, fehlende Inhalte usw. zu identifizieren. Eine entsprechende Tabelle wird an das Management- und Dokumentationsteam weitergeleitet. Dies wird Sie bei der Entwicklung einer neuen Strategie für die Strukturierung und Präsentation der Dokumentation unterstützen.

Informationsarchitektur erstellen Um das Wissensnetzwerk oder den Informationsfluss in der Konfigurationsdokumentation zu verstehen, kann das Erstellen einer Informationsarchitektur (IA) nützlich sein. Die Ergebnisse der Inhaltsprüfung dienen als gute Grundlage, um den Informationsfluss zu verstehen und zu entwickeln. Anschließend wird eine verbesserte Version der IA erstellt, um die Dokumentation besser zu organisieren und zu präsentieren. Diese verbesserte IA wird nicht nur den aktuellen Inhalt neu strukturieren, sondern auch Links und Forks zwischen verschiedenen Abschnitten der Dokumentation identifizieren und so ein effizientes Netzwerk schaffen. Beispielsweise kann auf den Inhalt von „Regeln konfigurieren“ ein Link folgen, der zu „Regeln mit Inline-Kommentaren deaktivieren“ führt. Es können auch andere Links dieser Art identifiziert werden, wodurch Beziehungen zwischen verschiedenen Abschnitten der Dokumentation entstehen.

Eine Inhaltsprüfung und eine IA liefern ausreichende Informationen, um ein detailliertes Inhaltsverzeichnis mit Links zu bestimmten Abschnitten und Unterabschnitten der Dokumentation zu erstellen. Das Erstellen separater Dateien für jeden Abschnitt und das Hinzufügen geeigneter Verweise auf andere Abschnitte kann einen Mehrwert für den gesamten Dokumentensatz schaffen. Für Nutzende, die zur Konfigurationsdokumentation gelangen, kann ein Inhaltsverzeichnis erstellt werden, was die Navigation auf der Website erleichtert. Das Inhaltsverzeichnis kann alle Überschriften der ersten und zweiten Ebene enthalten, um es kurz und gleichzeitig vollständig zu halten. Eine solche Praxis ist beispielsweise diejenige, die von Prettier (https://prettier.io/docs/en/index.html) zur Organisation der Dokumentation verwendet wird.

Die gesamte Dokumentation wird mithilfe von Markdown erstellt, um die Dinge einfach und gut zu organisieren. Es wird besonders darauf geachtet, dass die Dokumentation wiederverwendbar ist, da sie sich in Zukunft erweitern und ändern kann.

Zu verwendende Tools Einige wichtige Tools, die sich bei der Arbeit an dem Projekt als nützlich erweisen können, sind - Draw.io, um bei Bedarf Illustrationen für IA zu erstellen - Atom (oder ein ähnlicher Editor) zum Schreiben und Bearbeiten von Dokumenten in Markdown

- GitHub zur Sicherstellung der Versionskontrolle der Dokumentation

Meilensteine Von der Einreichung des Angebots bis zum Abschluss des Projekts stellen die folgenden vorläufigen Meilensteine sicher, dass das Projekt pünktlich abgeschlossen wird und den richtigen Ablauf im Prozess aufrechterhalten wird.

10. Juli 2020 bis 16. August 2020: Angebotsüberprüfung und -auswahl Ich gehe die Dokumentation von ESLint durch und entwickle die erforderlichen Fähigkeiten für die Abwicklung des Projekts (z. B. Verfassen von Markdown und Zusammenarbeit auf GitHub). Ich werde auch über GitHub zur Dokumentation beitragen und mich mit anderen austauschen, um die Dokumentation besser zu verstehen.

17. August 2020 bis 13. September 2020: Community-Beziehung Während der Community-Bonding-Phase werde ich meinen Vorschlag entsprechend den Gesprächen mit den Mentoren und den betroffenen Teams überarbeiten. Ich werde die Ziele und Meilensteine bei Bedarf auch bearbeiten. Außerdem werde ich die Tools auswählen, die dann für die Arbeit an dem Projekt verwendet werden.

14. September 2020 bis 19. September 2020: Inhaltsprüfung Zu Beginn des Projekts werde ich eine umfassende Prüfung der Inhalte der Konfigurationsdokumentation durchführen. Das Ziel besteht darin, Probleme mit dem Inhalt und der Präsentation hervorzuheben.

20. September 2020 bis 25. September 2020: Informationsarchitektur (IA) Nach der Inhaltsprüfung erstelle ich die IA der Konfigurationsdokumentation. Ich werde mich darauf konzentrieren, das Wissensnetzwerk auf verständliche Weise zu präsentieren. Dies trägt dann dazu bei, den Informationsfluss zu verbessern.

26. September 2020 bis 30. September 2020: Links und Referenz Ich werde die IA in dieser Phase analysieren, um Links und Verweise zwischen verschiedenen Abschnitten der Dokumentation zu skizzieren. Ich erstelle außerdem eine Hierarchie aller Abschnitte, um die IA im Prozess zu verbessern.

1. Oktober 2020 bis 3. Oktober 2020: Die endgültige Karte Mithilfe der Erkenntnisse aus der Inhaltsüberprüfung und der IA erstelle ich dann eine endgültige Karte, die in die neu organisierte Konfigurationsdokumentation eingefügt werden soll. Diese umfassende Karte enthält ein Inhaltsverzeichnis, eine Hierarchie von Themen und eine Liste mit Links und Querverweisen zwischen den Abschnitten der Dokumentation.

4. Oktober 2020 bis 5. Oktober 2020: Diskussion An dieser Stelle, also vor der Bearbeitung der Dokumentation, werde ich meine Erkenntnisse und Pläne den Mentoren und den betroffenen Teams präsentieren. Ihr Feedback hilft bei der Optimierung des Plans und bei Bedarf, um Änderungen vorzunehmen.

6. Oktober 2020 bis 20. Oktober 2020: Umformulierung und Bearbeitung In diesem Zeitraum bearbeite und aktualisiere ich die Abschnitte der Dokumente, in denen noch Verbesserungsbedarf besteht. Möglicherweise werden einige Abschnitte der Konfigurationsdokumentation neu geschrieben oder neue Elemente hinzugefügt. In dieser Phase liegt der Schwerpunkt darauf, sicherzustellen, dass die Dokumentation korrekt, aktualisiert, flexibel und wiederverwendbar ist.

21. Oktober 2020 bis 25. Oktober 2020: Korrekturen und Links In dieser Phase überprüfe ich meine eigene Arbeit, um grammatische und strukturelle Fehler zu beseitigen und meine Arbeit auf ihre Richtigkeit zu überprüfen. Außerdem werde ich Links und Verweise zwischen den Abschnitten gemäß der IA hinzufügen, um sicherzustellen, dass die Dokumentation der zuvor erstellten Knowledge Map entspricht.

26. Oktober 2020 bis 31. Oktober 2020: Endgültige Version für die Einreichung Ich verlinke alle Markdown-Dateien, erstelle ein Inhaltsverzeichnis und teile die Entwürfe mit den Mentoren. Dies dient als Einreichung des ersten Entwurfs in Form eines Komplettpakets.

1. November 2020 bis 5. November 2020: Erste Überprüfung In diesen fünf Tagen werde ich den ersten Entwurf mit meinen Mentoren besprechen. Ich werde ihr Feedback einholen und meine Ideen mit ihnen besprechen, um eine Liste der erforderlichen Änderungen zu erstellen.

6. November 2020 bis 12. November 2020: Erste Änderungen Mithilfe des Feedbacks der beratenden Personen werde ich den ersten Entwurf der Dokumentation bearbeiten. Die tatsächlichen Änderungen hängen von der Art der Kommentare und des Feedbacks ab. Als Dreh- und Angelpunkt der Bearbeitungsphase dienen jedoch die Ziele der Wiederverwendbarkeit, Genauigkeit und Flexibilität.

13. November 2020 bis 15. November 2020: Zweite Überprüfung Nach der Bearbeitung der ersten Bearbeitung werde ich noch einmal mit meinen Mentoren und den betroffenen Teams über den Fortschritt sprechen. Diese Diskussionen konzentrieren sich auf die Änderungen, die an der ersten Version vorgenommen wurden, sowie auf andere Probleme, die während des Bearbeitungsprozesses aufgetreten sind.

16. November 2020 bis 19. November 2020: Zweite Bearbeitung Anschließend werde ich vier Tage lang das Dokument bearbeiten. Die so entstandenen Versionen werden mit den beratenden Personen besprochen, um ihnen eine endgültige Form zu geben. Nach Abschluss dieser Phase liegen die Dokumente in der endgültigen Form vor, die dann auf die Website und in das GitHub-Repository hochgeladen werden können.

20. bis 23. November 2020: Inhalte auf der Website hochladen Nachdem Sie alle erforderlichen Änderungen vorgenommen haben, werden die Dokumente auf die Website hochgeladen. Alle Probleme, die im Rahmen des Prozesses auftreten, werden entsprechend behandelt, da wir noch ein paar Tage Zeit haben, um an der Dokumentation zu arbeiten.

24. bis 28. November 2020: Projektbericht In diesem Zeitraum von fünf Tagen wird ein detaillierter Bericht über das Projekt erstellt. Die Ziele, Schwierigkeiten, Probleme und die vorgestellten Lösungen sind Teil des Projektberichts. Der Bericht wird mit den Mentoren geteilt, die Feedback geben.

29. November 2020 bis 30. November 2020: Endgültige Einreichung Das Projekt wird zusammen mit allen Dateien und dem Projektbericht an die Mentoren gesendet. Im Rahmen eines Treffens/einer Diskussion mit den beratenden Personen und den betroffenen Teams wird das gesamte Projekt überprüft.

Während des gesamten Projekts werde ich die beratenden Personen weiter beraten, um ihr wertvolles Feedback zu erhalten. Alle diese Meilensteine können basierend auf den Gesprächen mit den beratenden Personen während des Community-Bonding- und Vorschlags-Review-Zeitraums geändert werden.

Über mich Ich habe einen Bachelor-Abschluss in Elektrotechnik und einen Abschluss in Technical and Professional Communication der North Carolina State University. Ich habe Erfahrung in den Bereichen technisches und professionelles Schreiben und Bearbeiten, Kommunikation und Content-Management, Web- und mobile Usability-Studien sowie das Entwerfen von Anleitungen. Ich habe als Sub-Editor für eine Onlinepublikation (Global Village Space) und als Communications Intern für Duke Forge an der Duke University gearbeitet. Außerdem interessiere ich mich für kreatives Schreiben.