Das Projekt der Wikimedia Foundation

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:
Die Wikimedia Foundation
Technischer Redakteur:
Pavithra Eswaramoorthy
Projektname:
Verbesserung der Dokumentation für die technischen Dokumentare und Videografen von Wikimedia
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

1. Über mich

Vor einigen Monaten wurde ich mit Open-Source-Software vertraut gemacht und war fast sofort von ihrem unbegrenzten Umfang überwältigt. Bei der Suche nach einem geeigneten Projekt stieß ich auf Open-Source-Initiativen wie Google Summer of Code und Outreachy. Google Season of Docs klang interessant und die Projektideen der Wikimedia Foundation weckten meine Neugier. Ich begann, mich näher damit zu beschäftigen.

Meine bisherige Reise war aufregend und verwirrend zugleich, mit vielen „Moment mal“, „Aha, jetzt verstehe ich“ und „Sollte ich das kommentieren?“. Die Wikimedia-Community hat mich bei jedem Schritt unterstützt. Vom Bearbeiten von Seiten bis zum Erstellen von Erweiterungen habe ich jeden Tag etwas Neues gelernt.

Wie erwartet diente der Bewerbungsprozess als Zugang zur Open-Source-Community. Dieser Vorschlag basiert auf meinen eigenen Erfahrungen als Anfänger.

2. Projekt

2.1. Umriss

Dieses Projekt zielt darauf ab, die Dokumentation für technische Redakteure und potenzielle Videografen bei Wikimedia zu verbessern. Ausgereifte Richtlinien für technische Dokumentationen würden zu einer besseren Gesamtdokumentation beitragen und Referenzen zum Erstellen von Screencasts würden eine effektive Demonstration von Softwarefunktionen ermöglichen. Die vorhandene Dokumentation in diesen Bereichen kann erweitert werden, um sowohl Neulinge als auch erfahrene Mitwirkende besser zu unterstützen. Für die Entwicklung dieses Netzwerks nützlicher Ressourcen wird ein inkrementeller Ansatz verwendet.

2.2. Ergebnisse

  • T197006 [https://phabricator.wikimedia.org/T197006] – Dokumentation für Dokumentaristen von Wikimedia verbessern:

    • Fügen Sie der Dokumentation/dem Styleguide Tipps und Beispiele hinzu. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Fügen Sie bestimmten Genres in Vorlagen und Vorschlägen für technische Dokumentationen MediaWiki-spezifische Informationen hinzu: Nutzerhandbücher, Anleitungen, Kurzanleitungen, Releasenotes und READMEs. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Richtlinien für die Priorisierung technischer Dokumentationen testen und verbessern [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Entwerfen Sie eine Strategie zur Sammlung von Inhalten für verschiedene Dokumentationsgenres.
    • Entwickeln Sie eine Kommunikations- und Zusammenarbeitsstrategie für die MediaWiki-Dokumentation.
    • Erstellen Sie eine Checkliste, anhand derer die Autoren ihre Dokumente vor der Veröffentlichung überprüfen können.
    • Die Dokumentationsstruktur für neue technische Redakteure erweitern. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Erstellen Sie eine Liste mit Aufgaben zur technischen Dokumentation, die für Hackathons geeignet sind. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Schaffen Sie einen Hub für technische Redakteure, der auf nützliche Ressourcen verweist.

  • Verbesserung der Dokumentation für die Videografen von MediaWiki:

    • Erstelle eine Kurzanleitung zum Erstellen eines allgemeinen Screencasts.
    • Entwerfen Sie MediaWiki-spezifische Screencast-Vorlagen für Schritt-für-Schritt-Anleitungen und Tutorials.

  • T214522 [https://phabricator.wikimedia.org/T214522] – Erstelle einen Screencast „Introduction to Phabricator“.

2.3. Stretch-Ziel

  • Überprüfen Sie den Inhalt noch einmal und aktualisieren Sie die WikiProject Screencast-Dokumentation. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentoren

Zulip ist die primäre Kommunikationsmethode mit meinen Mentoren. Die IRC-Kanäle und E-Mail-Adressen von Wikimedia werden für Diskussionen mit der Community verwendet. Diskussionen über spezifische Aufgaben finden im Kommentarbereich der Phabricator-Aufgaben statt.

4. Diskussion

Dieses Projekt ist grob in zwei Phasen unterteilt:

(i) Die vorhandenen Ressourcen für die technischen Redakteure von Wikimedia verbessern.

(ii) Nützliche Vorlagen für potenzielle Videografen erstellen.

(i) Verbesserung der vorhandenen Ressourcen für die technischen Autoren von Wikimedia.

In der Vergangenheit gab es mehrere Initiativen zur Verbesserung der MediaWiki-Dokumentation, die mit unterschiedlichem Erfolg verliefen. Beispiele:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

Aus diesen Bemühungen können wir schließen, dass bessere Ressourcen für technische Redakteure sich direkt auf die von ihnen erstellten Dokumente auswirken.

Im Folgenden finden Sie einen Ausschnitt aus dem zweiwöchigen Bericht einer Outreachy-Praktikantin 2018, Anna e só: https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/

„Der Stilguide von MediaWiki ist bei weitem nicht perfekt, vor allem weil er zu sehr auf externe Verweise setzt, ohne hervorzuheben, welche Praktiken er als die besten ansieht. Leider ist dieses Problem nicht auf MediaWiki beschränkt, sondern tritt auch in anderen Dokumenten auf, z. B. in den Best Practices für Übersetzungen. Autoren haben dann keine guten und zuverlässigen Ressourcen für ihre Arbeit, was es schwierig macht, eine Zielgruppe und einen geeigneten Schreibstil zu definieren. Und Nutzer, insbesondere neue Nutzer, haben möglicherweise Probleme, neue Konzepte und Prozesse zu verstehen.“

T197006 [https://phabricator.wikimedia.org/T197006] wirft auch Licht auf bestimmte Bereiche der Dokumentation technischer Texte, die verbessert werden müssen. Der beste Ausgangspunkt ist natürlich „Documentation/Style_guide“.

Sobald wir eine bessere Stilrichtlinie haben, sind die nächsten Dokumente geplant, die technische Redakteure durch die verschiedenen Phasen des technischen Schreibens führen. Die Dokumente müssen für Anfänger geeignet sein und gleichzeitig alle erforderlichen Informationen für die Autoren enthalten.

Die Vorbereitungsphase ist möglicherweise die wichtigste, da sie die Grundlage für das Dokument bildet. Um technische Redakteure in dieser Phase zu unterstützen, werden Referenzdokumente entwickelt, in denen einige effektive Möglichkeiten zum Erfassen relevanter Informationen und Tipps zur Strukturierung dieser Informationen mithilfe von Vorlagen beschrieben werden.

Dann kommt die Schreibphase. Den Autoren werden Beispiele für gute Arbeit vorgelegt, damit die Messlatte automatisch hoch gelegt wird. Außerdem wird eine Checkliste mit einer Reihe grundlegender Kriterien erstellt, die jedes Dokument erfüllen muss. Dies hilft den Autoren, ihre Dokumente vor der Veröffentlichung zu überprüfen.

Auch mit diesen Dokumenten benötigen neue technische Redakteure zusätzliche Hilfe, die wir ihnen geben müssen. Der Leitfaden für neue technische Redakteure wurde überarbeitet und eine Liste mit Aufgaben, die für Hackathons geeignet sind, wurde nach Schwierigkeitsgrad zusammengestellt.

Schließlich wird ein Dokument zum Verwalten und Pflegen der Dokumentation getestet und verbessert: „Priorisierung der technischen Dokumentation“.

Am Ende dieser Phase wird ein Hub mit Anleitungen, Ressourcen, Beispielen, Vorschlägen und Vorlagen für technisches Schreiben eingerichtet, der den Stilleitfaden für die Dokumentation unterstützt.

(ii) Nützliche Vorlagen für potenzielle Videografen erstellen.

„Eine der schwierigsten Möglichkeiten, etwas mit Grafiken zu lernen, ist das Lesen von Klartext. Stellen Sie sich auch vor, was passiert, wenn sich Ihr Handbuch auf die falsche Version der Software bezieht. Bei Texthandbüchern ist es oft unmöglich, eine Reihe von Aktionen nachzuvollziehen, wenn sich die Menüs und die Formulierungen in der Anwendung ändern, da uns alle Hinweise fehlen, die wir normalerweise verwenden würden.

Am besten lernen Sie, wenn ein Experte direkt neben Ihnen sitzt. Screencasts werden nur zwischen statischen Grafiken und einem fachkundigen Ansprechpartner eingesetzt. Wir sehen eine visuelle, bewegte Demo mit einer freundlichen Stimme. Außerdem können wir Texthinweise auf dem Bildschirm und Animationen verwenden. Ein Vorteil von Screencasts gegenüber Experten ist, dass sie jeden Tag und zu jeder Stunde abgespielt werden können.

Wir können einem Screencast auch übersetzte Untertitel hinzufügen, damit er von Personen mit anderen Muttersprachen angesehen werden kann, oder den Audiotrack durch eine andere Sprache ersetzen.“

Im obigen Ausschnitt des „The Screencasting Handbook“ [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] erklärt Ian Ozsvald die Bedeutung von Screencasts. Das kann besonders hilfreich sein für Anleitungen zum Einrichten der MediaWiki-Entwicklungsumgebung, zum Erstellen von Erweiterungen und zur Verwendung von Gerrit.

Ähnlich wie bei Vorlagen für Dokumente sorgt eine Standardvorlage für Screencasts für Einheitlichkeit und damit für eine bessere Nutzerfreundlichkeit. Außerdem bietet es potenziellen Videografen einen Rahmen für den Einstieg. Daher wird eine Kurzanleitung mit Vorlagen zum Erstellen von Einführungs- und Anleitungsvideos entwickelt. Die Dokumente enthalten Hinweise zur Tiefe der zu behandelnden Konzepte und einige Ideen für Screencasts für MediaWiki.

Die beste Möglichkeit, die obige Vorlage zu testen und sich auf das Stretch-Ziel vorzubereiten, besteht darin, mit den Tools und Vorlagen einen Screencast zu erstellen. Daher wird ein Screencast mit dem Titel „Einführung in Phabricator“ erstellt, in dem die Grundlagen der Verwendung von Phabricator behandelt werden. So werden auch die Bereiche hervorgehoben, die besprochen werden müssen.

Schließlich wurde die zentrale Referenzquelle für die Videografen von Wikimedia, WikiProject Screencast, überprüft und aktualisiert.

5. Vorläufiger Zeitplan

Kennenlernphase der Community (1. August bis 1. September)

  • Das Projekt mit meinen Mentoren im Detail analysieren.

  • Diskutieren Sie Folgendes:

    • Wie oft die Aufgaben überprüft werden sollen.
    • Sie können Zeitpläne freigeben und einen Wochen-/Tagesablauf festlegen.
    • Verfügbare Tools und Ressourcen
    • Zweiwöchentliche und tägliche Projektberichte.

  • Erstelle die erforderlichen Aufgaben und Unteraufgaben auf Phabricator.

  • Erstellen Sie Entwürfe, um persönliche Verpflichtungen während der Dokumententwicklungsphase auszugleichen.

Woche 1 (2. bis 8. September)

  • Verbessern Sie die Dokumentation/den Styleguide:

    • Der Schwerpunkt sollte auf den Best Practices und Standards in MediaWiki liegen.
    • Fügen Sie Beispiele für gute Arbeit hinzu und verbessern Sie die Sichtbarkeit der zugehörigen Seiten.

  • Leitfaden für neue technische Redakteure verbessern:

    • Erweitern Sie die Dokumentationsstruktur.

Woche 2 (9. bis 15. September)

  • Priorisierung der technischen Dokumentation:

    • Sehen Sie sich das Dokumentations-Workboard an und suchen Sie nach Beispielen für gute Aufgabenbeschreibungen und Priorisierungen.
    • Sehen Sie sich die Trends an und notieren Sie häufige Schwierigkeiten.
    • Verwenden Sie die Informationen und Beispiele, um die Priorisierungsstandards zu dokumentieren.

Woche 3 (16. bis 22. September)

  • Erstellen Sie die folgende zusätzliche Dokumentation für technische Redakteure:

    • Eine Checkliste, die Ihnen dabei hilft, die technische Dokumentation vor der Veröffentlichung durchzugehen.
    • Möglichkeiten, Inhalte für verschiedene Dokumentationsgenres effektiv zu erfassen.

Woche 4 (23. bis 29. September)

  • Fügen Sie den Vorlagen und Vorschlägen für technische Dokumentationen Informationen zum Verfassen von Texten in den gängigsten MediaWiki-Genres hinzu:

    • Dokumentieren Sie die Best Practices in MediaWiki für das Erstellen von Anleitungen, Kurzanleitungen, READMEs, Releasenotes und Anleitungen.

  • Fügen Sie Anweisungen hinzu, um die technische Kommunikation zu verbessern. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Woche 5 (30. September bis 6. Oktober)

  • Verbessern Sie die Dokumentation für das Onboarding neuer Mitbearbeiter:

    • Seite aktualisieren: Aufgaben zur technischen Dokumentation für Hackathons (To-do: Fügen Sie dieser Seite während des gesamten Projektzeitraums geeignete Aufgaben hinzu.)

  • Hub für technische Redakteure aufbauen

    • Erstellen Sie eine Landingpage mit Links zu nützlichen Seiten und Ressourcen.
    • Fügen Sie die erforderlichen Links zu den neuen und vorhandenen Seiten hinzu, um die Navigation zwischen ihnen zu erleichtern.

Woche 6 (7.–13. Oktober)

  • Erstellen Sie die folgenden Dokumente zum Erstellen von Videos für MediaWiki:

    • Eine Kurzanleitung zum Erstellen eines allgemeinen Screencasts, die auf das Screencast-Projekt verweist.
    • Vorlagen für: Schritt-für-Schritt-Anleitungen zur Verwendung einer Software/eines Tools; Anleitungen zur Entwicklung neuer Tools.

  • Erstellen Sie eine Liste mit Ideen für Screencasts zu MediaWiki.

Woche 7 (14.–20. Oktober)

  • Sehen Sie sich das Video „Einführung in Phabricator“ an:

    • Verwenden Sie die Vorlage (die Sie in der Vorwoche erstellt haben), um ein Script zu entwerfen.
    • Bewerten Sie die Effizienz der Vorlage und verbessern Sie sie bei Bedarf.
    • Holen Sie Feedback ein und stellen Sie den Entwurf fertig.

Woche 8 (21. bis 27. Oktober)

  • Veröffentlichen Sie das Video „Einführung in Phabricator“:

    • Wählen Sie die Software aus und installieren Sie sie.
    • Richten Sie die Umgebung ein und erstellen Sie den Screencast.
    • Notieren Sie sich die aufgetretenen Probleme und die Lösungen.

Woche 9 (28. Oktober bis 3. November)

  • Verbesserung der Dokumentation des Screencast-Projekts:

    • Die Struktur untersuchen und eventuelle Änderungen besprechen.
    • Sehen Sie sich die genannten Softwareprogramme an.
    • Recherchiere und aktualisiere die Liste der Software.

Woche 10 (4.–10. November)

  • Die Dokumentation des Screencast-Projekts weiter verbessern:

    • Anleitung und Scripts bewerten und verbessern
    • Sehen Sie sich die Screencast-Galerie an.

Woche 11 (11. bis 17. November)

  • Schließen Sie die Arbeit an der Screencast-Projektdokumentation ab:

    • Suchen Sie nach neueren Videos und fügen Sie sie der Galerie hinzu.
    • Nehmen Sie die erforderlichen strukturellen Änderungen vor.

Woche 12 (18. bis 24. November)

  • An ausstehenden Aufgaben arbeiten.

  • Abschließenden Bericht verfassen:

    • Rufen Sie die Berichte für alle zwei Wochen bzw. täglich auf und erfassen Sie die erforderlichen Informationen.
    • Planen Sie die Berichtsstruktur und schreiben Sie einen Entwurf.
    • Verbessern und fertigstellen Sie den Entwurf anhand des Feedbacks des Mentors.

Woche 13 (25. bis 29. November)

  • Reichen Sie den Abschlussbericht und die Bewertung durch den Mentor ein.

6. Fortschrittsanzeige

Meine Mentoren werden über Zulip täglich über den Fortschritt informiert. Die Wikimedia-Community kann meinen Fortschritt über Phabricator oder die alle zwei Wochen erscheinenden Projektberichte verfolgen.

7. Sonstige Verpflichtungen

Ich studiere Vollzeit und mein Herbstsemester fällt mit der Season of Docs-Zeitleiste zusammen. Daher habe ich Verpflichtungen, die sich auf Uniprüfungen beziehen.

Erste interne Prüfung: 18. bis 24. August

Zweite interne Prüfung: 29. September bis 6. Oktober

Prüfung am Ende des Semesters: 11. bis 30. November

Außerdem plane ich, dank der günstigen Lage dieses Jahr an meiner ersten öffentlichen Konferenz, der PyCon India vom 12. bis 15. Oktober, teilzunehmen. Ich glaube, es wäre eine gute Gelegenheit, neue Leute kennenzulernen und interessante Gespräche zu führen.

Um diese Verpflichtungen zu erfüllen, enthält der vorläufige Zeitplan weniger wichtige Aufgaben in den entsprechenden Wochen. Ich beabsichtige, im Herbstsemester nicht mehr als 20 Pflichtpunkte zu absolvieren, um genügend Zeit für die Entwicklung des Dokuments zu haben. (Ein regulärer Student sammelt durchschnittlich 25 Credits pro Semester.)