Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- ESLint
- Technischer Redakteur:
- Chawar
- Projektname:
- Konfigurationsdokumentation neu organisieren/umschreiben
- Projektdauer:
- Standardlaufzeit (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 Nutzerfreundlichkeit und Nützlichkeit der Dokumentation.
Projektübersicht Die Konfigurationsdokumentation von ESLint (https://eslint.org/docs/user-guide/configuring) enthält derzeit viele Informationen auf einer einzigen Seite. Trotz Überschriften, Zwischenüberschriften und angemessener Absätze auf der Seite kann die Dokumentation überwältigend sein. Es gibt keine Möglichkeit, einen bestimmten Bereich der Seite aufzurufen. Das ist frustrierend für Nutzer, die sich für einen bestimmten Bereich interessieren. Aufgrund dieser mangelnden Organisation können die Informationen auch verloren gehen, ihren Zweck nicht erfüllen und die Nutzer zu zusätzlichen Anstrengungen zwingen.
Diese Probleme lassen sich jedoch mit einer Reihe sorgfältiger Schritte beheben. Ich schlage als ersten Schritt bei dieser Umstrukturierung eine Inhaltsanalyse vor. Eine Inhaltsprüfung hilft nicht nur dabei, Probleme in der Präsentation der Informationen zu identifizieren, sondern zeigt auch die Mängel der Inhalte selbst auf (z.B. veraltete oder unvollständige Informationen). Anschließend werde ich die Informationsarchitektur (IA) erstellen, um das Wissensnetzwerk zu enthüllen. Auf diese Weise können wir die Informationen nach verschiedenen Themen gruppieren und Verbindungen zwischen verschiedenen eng verwandten Themen finden. Die Erkenntnisse aus diesen beiden Praktiken werden dann verwendet, um die Dokumentation auf einer Seite in mehrere Seiten aufzuteilen. Das gesamte Paket kann dann in Markdown verlinkt und mit Querverweisen versehen werden. So entsteht eine besser strukturierte Version der Konfigurationsdokumentation, die leichter zu bedienen und zu verstehen ist.
Motivation Obwohl ich schon seit einiger Zeit Open-Source-Software verwende, bin ich mit dem Begriff erst vor Kurzem vertraut geworden, ähnlich wie mit Linting-Software. Als ich anfing, Python (über edX) zu lernen, habe ich mich gefragt, wie winzige Fehler den gesamten Code durcheinanderbringen können. Ich dachte, es wäre schön, Ihre Codes irgendwie testen zu lassen und Ihre Fehler identifizieren zu lassen. Dann erfuhr ich von dem Begriff „Linting“. Ich habe noch keine Linting-Software verwendet, aber ich bin mir sicher, dass diese mir in den kommenden Tagen das Leben erheblich erleichtern werden.
Durch meinen Hintergrund in der Elektrotechnik und einige Erfahrung im Programmieren kann ich die Probleme beim Codieren und die Anforderungen von Programmierern besser nachvollziehen. Außerdem bin ich durch meinen Abschluss in technischer und beruflicher Kommunikation eine Fürsprecherin der Nutzer und möchte ihnen das Leben erleichtern. Meine Fähigkeiten und mein Fachwissen sind eine gute Kombination für dieses Projekt und werten die Dokumentation von ESLint auf.
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 überlastet. Für den Erfolg des Projekts ist es wichtig, dass die Navigation durch die Inhalte einfach und ohne Komplikationen erfolgt. Die wichtigsten Ziele des Projekts sind: – Eine umfassende Inhaltsüberprüfung durchführen – Eine Informationsarchitektur erstellen, um den Informationsfluss zu verstehen – Die Informationsarchitektur verbessern, um die Dokumentation neu zu strukturieren – Verknüpfungen und Verweise zwischen verschiedenen Abschnitten des Inhalts identifizieren – Teile der Dokumentation neu schreiben/bearbeiten, falls erforderlich, um die Anforderungen an die Neukonfiguration zu erfüllen
- Stellen Sie sicher, dass der Inhalt flexibel und wiederverwendbar ist.
Projektbeschreibung Die Konfiguration von ESLint ist eine wichtige Funktion, die ESLint anpassbar macht. Nutzer, die sich für die Konfiguration interessieren, sind höchstwahrscheinlich zu einem bestimmten Zeitpunkt an einem oder zwei Aspekten interessiert. Daher ist es wichtig, dass die Nutzenden zu dem für sie interessanten Thema geführt werden, damit sie auf effiziente Weise die Lösung finden. Die aktuelle Konfigurationsdokumentation für ESLint enthält viele nützliche Informationen, ist aber so aufgebaut, dass Nutzer sich überfordert, frustriert und verloren fühlen können. Wenn jemand beispielsweise mehr über die Verwendung von Drittanbieter-Plug-ins in ESLint erfahren möchte, muss er nach unten scrollen und sich die Informationen zur Angabe von Parser, Umgebungen und globalen Variablen ansehen. Der gesamte Ablauf ist bei den Nutzenden ermüdend und kann sie von der Website abschrecken. Wenn sich ein Nutzer in der Mitte der Seite befindet und zu einem bestimmten Bereich wechseln oder sich einfach nur ähnliche Themen ansehen möchte, ist das ebenfalls nicht einfach, da es keine solche Hilfe gibt. Diese Probleme müssen sofort behoben werden, da die Qualität jeder Dokumentation, unabhängig davon, wie gut sie formuliert ist, von ihrer Nützlichkeit abhängt. In der folgenden Diskussion stelle ich Lösungen für diese und andere ähnliche Probleme vor.
Inhaltsüberprüfung Der erste Schritt bei der Neuorganisation der Konfigurationsdokumentation besteht darin, eine umfassende Inhaltsüberprüfung durchzuführen. Ziel der Analyse ist es, einige wichtige Probleme wie veraltete Inhalte, Duplikate oder fehlende Inhalte zu identifizieren. Die daraus resultierende Tabelle für die Inhaltsanalyse wird dem Management- und Dokumentationsteam zur Verfügung gestellt, damit es Feedback geben kann. Dies wird Ihnen helfen, eine neue Strategie für die Strukturierung und Präsentation der Dokumentation zu entwickeln.
Informationsarchitektur erstellen Um das Wissensnetzwerk oder den Informationsfluss in der Konfigurationsdokumentation zu verstehen, kann das Erstellen einer Informationsarchitektur (IA) hilfreich sein. Die Ergebnisse der Inhaltsanalyse 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 die aktuellen Inhalte neu strukturieren, sondern auch Verknüpfungen und Verzweigungen zwischen verschiedenen Abschnitten der Dokumentation identifizieren und so ein effizientes Netzwerk schaffen. Auf den Inhalt in „Regeln konfigurieren“ kann beispielsweise ein Link folgen, der zu „Regeln mit Inline-Kommentaren deaktivieren“ führt. Andere solche Links können ebenfalls identifiziert werden und so Beziehungen zwischen verschiedenen Abschnitten der Dokumentation herstellen.
Ein Inhaltsverzeichnis und eine IA bieten angemessene Informationen, um ein detailliertes Inhaltsverzeichnis mit Links zu bestimmten Abschnitten und Unterabschnitten der Dokumentation zu erstellen. Wenn Sie für jeden Abschnitt separate Dateien erstellen und entsprechende Verweise auf andere Abschnitte hinzufügen, kann das den gesamten Dokumentensatz bereichern. Für Nutzer, die die Konfigurationsdokumentation aufrufen, kann ein Inhaltsverzeichnis erstellt werden, um die Navigation auf der Website zu erleichtern. Der Inhaltsverzeichnis kann alle Überschriften der ersten und zweiten Ebene enthalten, um es kurz und dennoch umfassend zu halten. Eine solche Praxis wird beispielsweise von Prettier (https://prettier.io/docs/en/index.html) zur Organisation der Dokumentation verwendet.
Die gesamte Dokumentation wird mit Markdown erstellt, um den Inhalt einfach und gut zu strukturieren. Besonderes Augenmerk wird darauf gelegt, dass die Dokumentation wiederverwendbar ist, da sie sich in Zukunft erweitern und ändern kann.
Tools to Use Einige wichtige Tools, die bei der Arbeit an einem Projekt nützlich sein 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 zur Versionskontrolle der Dokumentation
Meilensteine Die folgenden vorläufigen Meilensteine sorgen dafür, dass das Projekt von der Einreichung des Vorschlags bis zum Abschluss rechtzeitig abgeschlossen wird und der Prozess reibungslos abläuft.
10. Juli 2020 bis 16. August 2020: Prüfung und Auswahl des Angebots Ich werde die Dokumentation von ESLint durchgehen und die für das Projekt erforderlichen Fähigkeiten entwickeln (z. B. Markdown-Schreiben, 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: Bindung der Community Während der Bindungsphase verfeinert ich meinen Vorschlag gemäß den Gesprächen mit Mentoren und betroffenen Teams. Ich werde auch die Ziele und Meilensteine bearbeiten, falls erforderlich. Außerdem werde ich die Tools auf die Shortlist setzen, die dann für die Arbeit am Projekt verwendet werden.
14. September 2020 bis 19. September 2020: Inhaltsüberprüfung Zu Beginn des Projekts führe ich eine umfassende Inhaltsüberprüfung der Konfigurationsdokumentation durch. Ziel ist es, Probleme mit dem Inhalt und seiner Präsentation hervorzuheben.
20. September 2020 bis 25. September 2020: Informationsarchitektur (IA) Nach der Inhaltsüberprüfung erstelle ich die IA der Konfigurationsdokumentation. Ich werde mich darauf konzentrieren, das Wissensnetzwerk auf eine 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 Referenzen Ich analysiere in dieser Phase die IA, um Links und Verweise zwischen verschiedenen Abschnitten der Dokumentation abzubilden. Außerdem erstelle ich eine Hierarchie aller Abschnitte, um die IA zu verbessern.
1. Oktober 2020 bis 3. Oktober 2020: Die endgültige Karte Anhand der Erkenntnisse aus der Inhaltsüberprüfung und der IA erstelle ich dann eine endgültige Karte, die in der neu organisierten Konfigurationsdokumentation implementiert wird. Diese umfassende Übersicht enthält ein Inhaltsverzeichnis, eine Themenhierarchie und eine Liste mit Links und Querverweisen zwischen den Abschnitten der Dokumentation.
4. Oktober 2020 bis 5. Oktober 2020: Diskussion An diesem Punkt, also vor der Bearbeitung der Dokumentation, werde ich meine Ergebnisse und meinen Plan den Mentoren und betroffenen Teams präsentieren. Ihr Feedback hilft Ihnen, den Plan zu optimieren und bei Bedarf Änderungen vorzunehmen.
6. Oktober 2020 bis 20. Oktober 2020: Umformulieren und bearbeiten In diesem Zeitraum bearbeite und aktualisiere ich die Abschnitte der Dokumente, in denen Änderungen erforderlich sind. Einige Abschnitte der Konfigurationsdokumentation werden möglicherweise neu geschrieben oder neue Elemente hinzugefügt. In dieser Phase liegt der Fokus darauf, sicherzustellen, dass die Dokumentation korrekt, aktuell, flexibel und wiederverwendbar ist.
21. Oktober 2020 bis 25. Oktober 2020: Korrekturen und Verweise In dieser Phase überprüfe ich meine eigene Arbeit, um Grammatik- und Strukturfehler zu beseitigen und meine Arbeit auf Richtigkeit zu überprüfen. Außerdem füge ich gemäß der IA Links und Verweise zwischen den Abschnitten hinzu, damit die Dokumentation der zuvor erstellten Wissenskarte folgt.
26. Oktober 2020 bis 31. Oktober 2020: Endgültige Version zur 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 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 mir ihr Feedback anhören und meine Ideen mit ihnen besprechen, um eine Liste der erforderlichen Änderungen zu erstellen.
6. November 2020 bis 12. November 2020: Erste Änderungen Anhand des Feedbacks des Mentors bearbeite ich den ersten Entwurf der Dokumentation. Die tatsächlichen Änderungen hängen von der Art der Kommentare und des Feedbacks ab. Die Ziele der Wiederverwendbarkeit, Genauigkeit und Flexibilität bilden jedoch den Schwerpunkt der Bearbeitungsphase.
13. November 2020 bis 15. November 2020: Zweite Überprüfung Nach Abschluss der ersten Überarbeitungen werde ich den Fortschritt noch einmal mit meinen Mentoren und den zuständigen Teams besprechen. Diese Gespräche konzentrieren sich auf die Änderungen an der ersten Version und beleuchten auch alle anderen Probleme, die beim Bearbeiten auftreten können.
16. November 2020 bis 19. November 2020: Zweite Bearbeitung Anschließend werde ich vier Tage lang das Dokument bearbeiten. Die daraus resultierenden Versionen werden mit den Mentoren besprochen, um ihnen eine endgültige Form zu geben. Nach Abschluss dieser Phase haben die Dokumente die endgültige Form 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 alle erforderlichen Änderungen vorgenommen wurden, werden die Dokumente auf die Website hochgeladen. Alle dabei auftretenden Probleme werden entsprechend bearbeitet, da wir noch einige Tage Zeit haben, an der Dokumentation zu arbeiten.
24. November 2020 bis 28. November 2020: Projektbericht In diesen fünf Tagen wird ein detaillierter Projektbericht erstellt. Die Ziele, Herausforderungen, Probleme und die vorgestellten Lösungen sind Teil des Projektberichts. Der Bericht wird an die beratenden Personen weitergegeben, um Feedback zu erhalten.
29. November 2020 bis 30. November 2020: Letzte Einreichung Das Projekt wird zusammen mit allen Dateien und dem Projektbericht an die Mentoren gesendet. Eine Überprüfung des gesamten Projekts erfolgt in einem Meeting/Gespräch mit den Mentoren und den betroffenen Teams.
Während des gesamten Projekts werde ich mich immer wieder an die Mentoren wenden, um ihr wertvolles Feedback zu erhalten. Alle diese Meilensteine können basierend auf den Gesprächen mit Mentoren in der Phase des Kennenlernens und der Überprüfung des Vorschlags geändert werden.
Über mich Ich habe einen Bachelor-Abschluss in Elektrotechnik und einen Master-Abschluss in technischer und beruflicher Kommunikation 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 Nutzung sowie Lehrdesign. Ich habe als Redakteurin für eine Onlinepublikation (Global Village Space) und als Kommunikationspraktikantin für Duke Forge an der Duke University gearbeitet. Außerdem interessiere ich mich für kreatives Schreiben.