Das Projekt der Wikimedia Foundation

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:
Wikimedia Foundation
Technischer Redakteur:
Pavithra Eswaramoorthy
Projektname:
Verbesserte Dokumentation für die technischen Dokumentare und Videofilmer von Wikimedia
Projektdauer:
Standarddauer (3 Monate)

Projektbeschreibung

1. Über mich

Ich wurde vor einigen Monaten mit Open-Source-Software vertraut und fühlte mich fast sofort überfordert von ihrem unendlichen Umfang. Ich lernte von Open-Source-Initiativen wie Google Summer of Code und Outreachy kennen. Die Google Season of Docs schien interessant und die Projektideen der Wikimedia Foundation haben meine Neugier geweckt. Also begann ich, mich weiter zu erforschen.

Meine Reise war bisher genauso aufregend und verwirrend: „Moment, was?“, „Ahh, ich verstehe!“ und „Soll ich mich dazu äußern?“. Die Wikimedia-Community hat mich bei jedem Schritt unterstützt. Ich lerne jeden Tag etwas Neues dazu – vom Bearbeiten von Seiten bis zum Erstellen von Erweiterungen.

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

2. Projekt

2.1. Umriss

Ziel dieses Projekts ist es, die Dokumentation für technische Redakteure und potenzielle Videofilmer in Wikimedia zu verbessern. Eine Reihe ausgereifter Richtlinien für die technische Dokumentation würde dazu beitragen, die Dokumentation insgesamt zu verbessern, 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 Neueinsteiger als auch erfahrene Beitragende besser zu unterstützen. Zur Entwicklung dieses Netzwerks nützlicher Ressourcen wird ein inkrementeller Ansatz verfolgt.

2.2. Ergebnisse

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

    • Tipps und Beispiele zur Dokumentation/im Styleguide hinzufügen [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Fügen Sie MediaWiki-spezifische Informationen zu bestimmten Genres in den Vorlagen und Vorschlägen der technischen Dokumentation hinzu: Nutzerhandbücher, Anleitungen, Quick-Start-Leitfäden, Versionshinweise und Readme-Dateien. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Testen und verbessern Sie die Richtlinien für die Priorisierung der technischen Dokumentation. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Eine Strategie zur Inhaltserfassung für verschiedene Dokumentationsgenres entwerfen
    • Eine Strategie für die Kommunikation und Zusammenarbeit für die MediaWiki-Dokumentation entwerfen
    • Erstellen Sie eine Checkliste, anhand derer Autoren ihre Dokumente vor der Veröffentlichung überprüfen können.
    • Erweitern Sie die Dokumentationsstruktur für neue technische Redakteure. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Erstellen Sie eine Liste mit Aufgaben der technischen Dokumentation, die für Hackathons geeignet sind. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Einen Hub für technische Redakteure schaffen, der auf nützliche Ressourcen verweist.

  • Verbesserung der Dokumentation für Videofilmer 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]– Einen Screencast „Introduction to Phabricator“ erstellen

2.3. Dehnziel

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

3. Mentoren

Zulip wird die primäre Art der Kommunikation mit meinen Mentoren sein. Die IRC-Kanäle und die E-Mail-Adresse von Wikimedia werden für Diskussionen mit der Community verwendet. Diskussionen über bestimmte Aufgaben finden im Kommentarbereich der Aufgaben von Phabricator statt.

4. Diskussion

Dieses Projekt ist grob in zwei Phasen unterteilt:

(i) Verbesserung der vorhandenen Ressourcen für technische Autoren von Wikimedia

(ii) Nützliche Vorlagen für potenzielle Videofilmer erstellen

(i) Verbesserung der vorhandenen Ressourcen für technische Redakteure bei Wikimedia.

In der Vergangenheit gab es mehrere Initiativen zur Verbesserung der MediaWiki-Dokumentation mit unterschiedlichem Erfolg. Hier einige 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

Durch diese Bemühungen wissen wir, dass bessere Ressourcen für technische Redakteure direkte Auswirkungen auf die von ihnen erstellten Dokumente haben werden.

Nachfolgend finden Sie einen Ausschnitt aus dem zweiwöchentlichen Bericht einer Praktikumskraft von Outreachy 2018, Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

„Der Styleguide von MediaWiki ist bei Weitem nicht perfekt, insbesondere weil er zu viel auf externen Referenzen basiert, ohne hervorzuheben, welche Praktiken es als die besten betrachtet. Leider ist dieses Problem nicht nur auf MediaWiki beschränkt, wie es auch in anderen Dokumenten wie den Best Practices für Übersetzungen auftritt. Autoren haben am Ende keine guten und zuverlässigen Ressourcen für ihre Arbeit, was dazu führt, dass es schwierig ist, eine Zielgruppe und einen angemessenen Schreibstil festzulegen. Und Nutzende, insbesondere neue Nutzende, haben möglicherweise Schwierigkeiten, neue Konzepte und Prozesse zu verstehen.“

T197006 [https://phabricator.wikimedia.org/T197006] befasst sich auch mit bestimmten Bereichen der technischen Dokumentation, die verbessert werden müssen. Offensichtlich ist Documentation/Style_guide der Ausgangspunkt.

Sobald wir einen besseren Styleguide haben, werden die nächsten Dokumente geplant, um technische Redakteure durch die verschiedenen Phasen des technischen Verfassens zu führen. Die Dokumente müssen für Einsteiger geeignet sein und gleichzeitig alle erforderlichen Informationen für die Autoren enthalten.

Die Vorbereitungsphase ist möglicherweise die wichtigste, da sie das Fundament bildet, auf dem das Dokument aufbaut. Um technische Redakteure in dieser Phase zu unterstützen, werden Referenzdokumente entwickelt, in denen einige effektive Möglichkeiten zum Sammeln relevanter Informationen beschrieben werden. Außerdem erhalten Sie Tipps zur Strukturierung dieser Informationen mithilfe von Vorlagen.

Dann kommt die Schreibphase. Autoren erhalten Beispiele für gute Arbeiten, um die Messlatte automatisch hoch zu setzen. Darüber hinaus wird eine Checkliste mit einer Reihe grundlegender Kriterien erstellt, die jedes Dokument erfüllen muss. Dies erleichtert es 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 zur Verfügung stellen müssen. Der Leitfaden für neue technische Redakteure wurde verfeinert und eine Liste von Aufgaben erstellt, die für Hackathons geeignet sind, basierend auf dem Schwierigkeitsgrad.

Abschließend wurde ein Dokument zur Priorisierung der technischen Dokumentation getestet und verbessert, um den Prozess der Verwaltung und Pflege der Dokumentation zu verstehen.

Am Ende dieser Phase wird ein Hub mit technischen Handbüchern, Ressourcen, Beispielen, Vorschlägen und Vorlagen zur Unterstützung des Styleguides für die Dokumentation eingerichtet.

(ii) Nützliche Vorlagen für potenzielle Videofilmer erstellen

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

Am besten lernen Sie, wenn sich ein Experte direkt neben Ihnen setzt. Bei Screencasts wird zwischen statischen Grafiken gesprochen, sodass ein Experte in der Nähe ist. Wir erhalten eine visuelle, bewegende Demo mit einer freundlichen Stimme, wir können auch Textanmerkungen auf dem Bildschirm und Animationen einfügen. Screencasts haben gegenüber einem Experten den Vorteil, dass sie zu jeder Stunde und jeden Tag nach Belieben abgespielt werden können.

Wir können einem Screencast auch übersetzte Untertitel hinzufügen, damit sie von Nicht-Muttersprachlern angesehen werden können, oder die Audiotracks durch eine andere Sprache ersetzen.“

Im obigen Snippet aus „The Screencasting Handbook“ [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf] erklärt Ian Ozsvald die Bedeutung von Screencasts. Sie eignet sich besonders für Anleitungen zum Einrichten der MediaWiki-Entwicklungsumgebung, zum Schreiben von Erweiterungen, zur Verwendung von Gerrit und mehr.

Ähnlich wie Vorlagen für Dokumente fördert eine Standardvorlage für Screencasts Einheitlichkeit und verbessert dadurch die Nutzererfahrung. Außerdem erhalten potenzielle Videofilmer einen Rahmen für den Einstieg. Daher wurde eine Kurzanleitung entwickelt, gefolgt von Vorlagen zum Erstellen von Einführungs- und Tutorials. Die Dokumente enthalten Hinweise auf die zu behandelnden Konzepte und einige Screencast-Ideen für MediaWiki.

Die beste Möglichkeit, die obige Vorlage zu testen und sich auf das erweiterte Ziel vorzubereiten, ist die Erstellung eines Screencasts mit den Tools und Vorlagen. Daher wird der Screencast „Introduction to Phabricator“ erstellt, der die Grundlagen der Verwendung von Phabricator behandelt. Bei diesem Prozess werden auch die Bereiche hervorgehoben, die diskutiert werden müssen.

Das WikiProject Screencast, die zentrale Referenz für die Videofilmer von Wikimedia, wird geprüft und aktualisiert.

5. Vorläufiger Zeitplan

Community-Bonding-Zeitraum (1. August bis 1. September)

  • Gemeinsam mit meinen Mentoren das Projekt detailliert analysieren.

  • Diskussionsthemen:

    • Wie oft die Aufgaben überprüft werden sollten.
    • Teile Zeitpläne und entscheide dich für einen wöchentlichen/täglichen Workflow.
    • Tools und Ressourcen, die verwendet werden können.
    • Zweiwöchentliche und tägliche Projektberichte.

  • Erstellen Sie die erforderlichen Aufgaben und Unteraufgaben in Phabricator.

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

Woche 1 (2.–8. September)

  • Verbessern Sie die Dokumentation/den Styleguide:

    • Verlegen Sie den Schwerpunkt darauf, die Best Practices und Standards auf MediaWiki zu veranschaulichen.
    • Nennen Sie Beispiele für gute Arbeit und verbessern Sie die Sichtbarkeit der verknüpften Seiten.

  • Verbesserung des Leitfadens für neue technische Redakteure:

    • Maximieren Sie die Dokumentationsstruktur.

Woche 2 (9.–15. September)

  • Priorisierung der technischen Dokumentation:

    • Bewerten Sie die Arbeitstafel der Dokumentation und finden Sie Beispiele für gute Aufgabenbeschreibungen und Priorisierungen.
    • Studiere die Trends und notiere häufige Schwierigkeiten.
    • Verwenden Sie die Informationen und Beispiele, um die Priorisierungsstandards zu dokumentieren.

Woche 3 (16.–22. September)

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

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

Woche 4 (23.–29. September)

  • Fügen Sie den Vorlagen und Vorschlägen der technischen Dokumentation Informationen über Texte in den gängigsten MediaWiki-Genres hinzu:

    • Dokumentieren Sie auf MediaWiki die Best Practices für das Schreiben von Nutzerhandbüchern, Quick Start-Leitfäden, Readme-Dateien, Versionshinweisen und Anleitungen.

  • Fügen Sie Anleitungen hinzu, um die Reife der technischen 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)

  • Verbesserung der Dokumentation für die Einarbeitung neuer Mitbearbeiter:

    • Aktualisieren Sie die Seite: Aufgaben in der technischen Dokumentation für Hackathons. (Zu erledigen: Fügen Sie dieser Seite während der Projektlaufzeit 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, der auf das Screencast-Projekt verweist.
    • Vorlagen für: Anleitungen zur Verwendung einer Software bzw. eines Tools; Anleitungen zur Entwicklung neuer Tools.

  • Erstelle eine Liste mit Screencast-Ideen für MediaWiki.

Woche 7 (14.–20. Oktober)

  • Am Video „Introduction to Phabricator“ arbeiten:

    • Verwenden Sie die Vorlage, die Sie in der letzten Woche erstellt haben, um ein Skript zu entwerfen.
    • Schätzen Sie die Effizienz der Vorlage ab und verbessern Sie sie bei Bedarf.
    • Holen Sie Feedback ein und stellen Sie den Entwurf fertig.

Woche 8 (21.–27. Oktober)

  • Veröffentlichen Sie das Video „Introduction to 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 Lösungen.

Woche 9 (28. Oktober–3. November)

  • Verbessern Sie die Dokumentation des Screencast-Projekts:

    • Sehen Sie sich die Struktur an und besprechen Sie eventuell erforderliche Änderungen.
    • Lesen Sie sich die erwähnten Softwareprogramme durch.
    • Recherchieren und aktualisieren Sie die Liste der Software.

Woche 10 (4.–10. November)

  • Verbessern Sie weiter die Screencast-Projektdokumentation:

    • Bewerten und verbessern Sie die Anleitung und die Skripts.
    • Sieh dir die Screencast-Galerie an.

Woche 11 (11.–17. November)

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

    • Finde neuere Videos und füge sie der Galerie hinzu.
    • Nehmen Sie die erforderlichen strukturellen Änderungen vor.

Woche 12 (18.–24. November)

  • Arbeiten Sie an ausstehenden Aufgaben.

  • Erstellen Sie den endgültigen Bericht:

    • Beziehen Sie sich auf die zweiwöchentlichen/täglichen Berichte und sammeln Sie die erforderlichen Informationen.
    • Planen Sie die Berichtsstruktur und schreiben Sie einen Entwurf.
    • Den Entwurf basierend auf dem Feedback der beratenden Person optimieren und fertigstellen.

Woche 13 (25.–29. November)

  • Einreichen des Abschlussberichts und Bewertung durch Mentoren

6. Fortschrittsverfolgung

Meine Mentoren werden über Zulip täglich über den Fortschritt informiert. Die Wikimedia-Community kann meinen Fortschritt über Phabricator oder die zweiwöchentlichen Projektberichte verfolgen.

7. Sonstige Verpflichtungen

Ich bin Vollzeitstudentin und mein akademisches Herbstsemester überschneidet sich mit dem Zeitplan für die Saison von Google Docs. Daher gehört zu meinen Verpflichtungen Hochschulprüfungen.

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

Aufgrund der günstigen Lage in diesem Jahr möchte ich auch an meiner ersten öffentlichen Konferenz, der PyCon India, vom 12. bis 15. Oktober teilnehmen. Ich denke, dies eine gute Gelegenheit, neue Leute kennenzulernen und aufschlussreiche Gespräche zu führen.

Um diese Verpflichtungen zu verwalten, enthält der vorläufige Zeitplan weniger wichtige Aufgaben in den entsprechenden Wochen. Ich beabsichtige, im Herbstsemester nicht mehr als 20 Hauptpunkte zu erwerben, um genügend Zeit für die Entwicklung der Dokumente zu haben. (Ein normaler Student erreicht pro Semester durchschnittlich 25 Leistungseinheiten)