Diese Seite wurde von der Cloud Translation API übersetzt.

ESLint-Projekt

Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel 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 neu zu strukturieren und eine effektive Informationsarchitektur zu schaffen. Dies erleichtert die Navigation und verbessert die Nutzungsfreundlichkeit und Nützlichkeit der Dokumentation.

Projektzusammenfassung Die Konfigurationsdokumentation von ESLint (https://eslint.org/docs/user-guide/configure) bietet im aktuellen Zustand viele Informationen auf einer einzigen Seite. Trotz der Vorhandensein von Überschriften, Zwischenüberschriften und entsprechenden 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 an einem bestimmten Bereich interessiert ist, frustrierend ist. Die Informationen können aufgrund dieser mangelnden Organisation auch verloren gehen, nicht ihren Zweck erfüllen und die Nutzenden zu zusätzlichen Anstrengungen auffordern.

Diese Probleme lassen sich jedoch durch eine Reihe sorgfältiger Schritte beheben. Ich schlage vor, dass wir in dieser Umstrukturierung als ersten Schritt eine Inhaltsprüfung durchführen. Eine Inhaltsüberprüfung hilft nicht nur dabei, Probleme in der Präsentation der Informationen zu erkennen, sondern zeigt auch Mängel der Inhalte selbst (z.B. veraltete oder unvollständige Informationen) auf. Anschließend plane ich die Erstellung der Informationsarchitektur (IA) zur Enthüllung des Wissensnetzwerks. So können wir die Informationen nach verschiedenen Themen gruppieren und Verbindungen zwischen verschiedenen eng verwandten Themen finden. Die durch diese beiden Methoden gewonnenen Erkenntnisse werden dann verwendet, um die einseitige Dokumentation in mehrere Seiten aufzuteilen. Das gesamte Paket kann dann in Markdown verknüpft und verglichen werden. Daher gibt es eine besser strukturierte Version der Konfigurationsdokumentation, die übersichtlicher und leichter verständlich ist.

Motivation Trotz der Tatsache, dass ich bereits seit einiger Zeit Open-Source-Software verwende, ist mir der Begriff noch ziemlich neu, ähnlich wie mein Wissen über Linting-Software. Als ich anfing, Python (über edX) zu lernen, fragte ich mich, wie winzige Fehler den ganzen Code durcheinanderbringen können. Ich dachte, es wäre schön, Ihre Codes irgendwie testen zu lassen und Ihre Fehler zu identifizieren. Dann erfuhr ich vom Begriff „Linting“. Ich habe bisher noch keine Linting-Software verwendet, bin aber sicher, dass sie mir in den kommenden Tagen das Leben erheblich erleichtern werden.

Mit meinem Hintergrund in Elektrotechnik und einiger Erfahrung in der Programmierung kann ich die Probleme des Programmierens und die Anforderungen von Programmierern besser verstehen. Außerdem bin ich durch meinen Abschluss in Technischer und beruflicher Kommunikation ein Verfechter der Nutzenden und versuche, das Leben für die Menschen zu vereinfachen. Meine Fähigkeiten und mein Fachwissen werden für dieses Projekt eine gute Kombination sein und einen Mehrwert für die ESLint-Dokumentation schaffen.

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 Inhaltsaudits durchführen - Informationsarchitektur erstellen, um den Informationsfluss zu verstehen - Informationsarchitektur zu verbessern, um die Dokumentation neu zu organisieren - Links und Verweise zwischen verschiedenen Abschnitten der Inhalte identifizieren - Teile der Dokumentation überarbeiten/bearbeiten, falls notwendig, um die Anforderungen der Neukonfiguration zu erfüllen

- Sicherstellen, dass die Inhalte flexibel und wiederverwendbar sind

Projektbeschreibung Die Konfiguration von ESLint ist eine wichtige Funktion, durch die ESLint anpassbar ist. Benutzer, die sich für die Konfiguration interessieren, 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, aber sie ist so strukturiert, dass sich die Nutzer überfordert, frustriert und verloren fühlen. 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 Variablen zu lesen. Die gesamte Vorgehensweise ist für die Nutzenden müde und kann sie von der Website abschrecken. Gleichermaßen ist es keine leichte Aufgabe für Nutzende, die sich irgendwo in der Mitte der Seite befinden und zu einem bestimmten Abschnitt gehen oder sich nur ähnliche Themen ansehen möchten, da ihnen 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 ihrer Nützlichkeit abhängt. In der folgenden Diskussion schlage ich Lösungen für diese und andere verwandte Probleme vor.

Inhaltsprüfung Der erste Schritt bei der Neuorganisation der Konfigurationsdokumentation wäre die Durchführung einer umfassenden Inhaltsprüfung. Ziel der Prüfung ist es, einige zentrale Probleme wie veraltete Inhalte, Duplikate, fehlende Inhalte usw. zu identifizieren. Eine daraus erstellte Tabelle zur Inhaltsüberprüfung wird mit dem Management- und Dokumentationsteam geteilt, um dort Feedback zu erhalten. 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) wertvoll sein. Die Ergebnisse des Inhaltsaudits dienen als gute Grundlage, um den Informationsfluss zu verstehen und weiterzuentwickeln. Anschließend wird eine verbesserte Version der IA erstellt, um die Dokumentation besser zu strukturieren und zu präsentieren. Diese verbesserte IA wird nicht nur den aktuellen Inhalt neu strukturieren, sondern auch Links und Verzweigungen zwischen verschiedenen Abschnitten der Dokumentation identifizieren, wodurch ein effizientes Netzwerk geschaffen wird. Beispielsweise kann auf den Inhalt von „Regeln konfigurieren“ ein Link folgen, der zu „Regeln mit Inline-Kommentaren deaktivieren“ führt. Andere solche Links können ebenfalls 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 bedeuten. Für Nutzende, die auf die Konfigurationsdokumentation gelangen, kann ein Inhaltsverzeichnis erstellt werden, was ihren Weg auf der Website erleichtert. Das Inhaltsverzeichnis kann alle Überschriften der ersten und zweiten Ebene enthalten, um es kurz, aber umfassend 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 mit Markdown erstellt, um alles einfach und gut zu organisieren. Es wird besonders darauf geachtet, dass die Dokumentation wiederverwendbar ist, da sie sich in Zukunft möglicherweise ändern oder erweitern 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 die IA zu erstellen - Atom (oder ein ähnlicher Editor) zum Schreiben und Bearbeiten von Dokumenten in Markdown

– GitHub, um die Versionskontrolle der Dokumentation sicherzustellen

Meilensteine Von der Einreichung des Vorschlags bis zum Abschluss des Projekts sorgen die folgenden vorläufigen Meilensteine dafür, dass das Projekt pünktlich abgeschlossen wird und den richtigen Ablauf 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 Durchführung des Projekts (z. B. das Schreiben von Markdown und die Zusammenarbeit auf GitHub). Ich werde auch über GitHub zur Dokumentation beitragen und mit anderen Personen in Kontakt treten, um die Dokumentation besser zu verstehen.

17. August 2020 bis 13. September 2020: Austausch mit der Community Während dieser Phase werde ich meinen Vorschlag entsprechend den Gesprächen mit den Mentoren und den betroffenen Teams optimieren. 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 führe ich eine umfassende Inhaltsprüfung der Konfigurationsdokumentation durch. 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 so zu präsentieren, dass es verständlich ist. Dies trägt dann dazu bei, den Informationsfluss zu verbessern.

26. September 2020 bis 30. September 2020: Links und Referenz In dieser Phase analysiere ich die IA, um Links und Verweise zwischen verschiedenen Abschnitten der Dokumentation zu skizzieren. Außerdem werde ich eine Hierarchie aller Abschnitte erstellen, wodurch die IA im Prozess verbessert wird.

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

4. Oktober 2020 bis 5. Oktober 2020: Diskussion An dieser Stelle, also vor der Bearbeitung der Dokumentation, werde ich meine Ergebnisse 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 werde ich die Abschnitte von Dokumenten, die bearbeitet werden müssen, bearbeiten und aktualisieren. Möglicherweise werden einige Abschnitte der Konfigurationsdokumentation neu geschrieben oder neue Elemente hinzugefügt. In dieser Phase liegt der Fokus darauf, dass die Dokumentation korrekt, aktuell, 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 noch einmal zu überprüfen, ob meine Arbeit korrekt ist. 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 beratenden Personen. Dies dient als Einreichung des ersten Entwurfs in Form eines vollständigen Pakets.

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 Ausgangspunkt der Bearbeitungsphase dienen jedoch die Ziele der Wiederverwendung, 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. Der Schwerpunkt dieser Diskussionen liegt auf den Ä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 Bearbeitungen Anschließend widme ich vier Tage der Bearbeitung des Dokuments. Die so entstandenen Versionen werden mit den beratenden Personen besprochen, um ihnen eine endgültige Form zu geben. Die Dokumente sind nach Abschluss dieser Phase in der endgültigen Form verfügbar und können auf die Website und in das GitHub-Repository hochgeladen werden.

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

24. November 2020 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 werden Teil des Projektberichts sein. Der Bericht wird mit den Mentoren geteilt, die ihr 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 einer Besprechung/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 Mentoren während der Bindungs- und Überprüfungsphasen geändert werden.

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