VLC-Projekt

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:
VLC
Technischer Redakteur:
Abhishek Pratap Singh
Projektname:
Modernisierung der VLC-Nutzerdokumentation fortsetzen
Projektdauer:
Standardlänge (3 Monate)

Projektbeschreibung

AKTUELLER STATUS DER DOKUMENTATION

Die VLC-Nutzerdokumentation wird gerade modernisiert und aktualisiert. Die Umstellung von der wikibasierten älteren Dokumentation[1] auf die moderne Sphinx-basierte Nutzerdokumentation[2], die auf ReadTheDocs gehostet wird, ist in vollem Gange.

ZIELGRUPPE

Die Zielgruppe sind sowohl neugierige Nutzer, die die Funktionen des VLC-Mediaplayers über einen gewöhnlichen Mediaplayer hinaus erkunden möchten, und in gewissem Maße als einfacher Leitfaden für Entwickler nützlich. Daher plane ich, sowohl GUI-basierte Anleitungen (einschließlich Bildern, sofern relevant) als auch CLI-basierte Methoden (zusammen mit Code-Snippets) einzubinden, damit die Endnutzer freie Wahl haben.

Ich bin der Meinung, dass die Sprache der Dokumentation (insbesondere des Abschnitts mit der GUI) so gekürzt werden sollte, dass eine Person, die nur geringfügig mit einem Computer in Berührung kommt, den Leitfaden verstehen und umsetzen kann. Andererseits sollte es nicht zu lang oder erklärend sein (insbesondere im Abschnitt zur Befehlszeile), dass die Programmierer das Interesse verlieren.

Das richtige Gleichgewicht lässt sich erreichen, indem Sie die Voraussetzungen am Anfang der Seite erwähnen oder optionale Abschnitte beibehalten, die versierte Nutzer überspringen können.

Die Zielgruppe für die Übersetzungen sind Entwickler/Nutzer von VLC, die gute Englischkenntnisse und gute Kenntnisse der Sprache haben, in die sie übersetzen.

TOOLS

Die neue Dokumentation wird mit Sphinx erstellt und auf ReadTheDocs gehostet. Das Versionskontrollsystem wird in GitLab implementiert. Ich hatte in der Vergangenheit Erfahrung mit Git und GitHub, was mir geholfen hat, GitLab kennenzulernen, auch wenn es einige andere Funktionen gab, deren Erlernen einige Zeit in Anspruch nahm.

Ich hatte von Sphinx gelesen, als ein anderer Open-Source-Begeisterter bemerkte, wie viele Organisationen ihn für die Erstellung ihrer Dokumentation verwenden (anhand des bemerkenswerten Beispiels von Blender, das Sphinx für die Erstellung des Benutzerhandbuchs[3] und der API-Dokumentation[4] verwendet).

Ich war mit ReadTheDocs ein wenig vertraut, einem guten Tool für die Versionierung und das Hosting technischer Dokumentationen. Daher konnte ich die VLC-Dokumentation ohne große Probleme erstellen und bin mit reStructured Text, der verwendeten Formatierung, vertraut.

Für Übersetzungen verwendet VLC Babel, um .po-Dateien zu generieren, um i18n und l10n zu implementieren. Derzeit mache ich mich mit dem Babel-Workflow und dem Erstellen von .mo-Dateien mit Sphinx vertraut.

Ich beabsichtige, die Einarbeitungszeit zu nutzen, um mich mit den Feinheiten der oben genannten Tools vertraut zu machen.

LEITFADEN UND WOCHENPLAN

Im Rahmen des Projekts 2019 sind bereits Teile der Installation, Benutzeroberfläche, Audio, Video, Wiedergabe usw. (die meisten grundlegenden Funktionen) abgedeckt. Daher möchte ich für das Projekt 2020 den Abschnitt zur erweiterten Nutzung der Nutzerdokumentation aktualisieren und bearbeiten.

LEISTUNGEN 1 [Woche 1–2]: Aktualisiere die Transcodierungsdokumentation wie unter 7[5] erwähnt.

  • Transcodieren
  • Mehrere Videos transcodieren
  • Logo hinzufügen
  • Videos zusammenführen
  • Audio extrahieren und Audio aus einer Datei extrahieren
  • DVD reißen

DELIVERABLE 2 [Week 3–4]: Update Using VLC as a web-plugin[6], während Tests in Firefox 77, Chrome 83 und Edge 83 durchgeführt werden.

  • Webseiten mit Videos erstellen
  • Tag-Attribute einbetten
  • Beschreibung der JavaScript API

LEITERFUNKTION 3 [Woche 5]: Testen Sie die Befehle der Befehlszeile[7] und aktualisieren Sie sie entsprechend.

  • Streams
  • Auswahl der Module
  • Artikelspezifische Optionen
  • Filter

Woche 6: Pufferwoche für die obigen drei Liefergegenstände.

LEISTUNGEN 4 [Woche 7–8]: Vorbereitung auf Übersetzungen. Neben der Aktualisierung werde ich mich auf Übersetzungen in andere Sprachen vorbereiten. Das ist wichtig, da Nutzer ohne Englischkenntnisse die Dokumentation nach der Übersetzung lesen können. Außerdem wäre VLC einen Schritt näher an der Weltherrschaft[8].

Wie im Abschnitt „Tools“ des Vorschlags erwähnt, verwendet VLC derzeit Babel, um .po-Dateien für Übersetzungen zu generieren. Ich dokumentiere den Prozess für einen Nutzer/Freiwilligen, um:

  • Laden Sie die Basisdokumentation herunter und erstellen Sie sie lokal.
  • Verwenden Sie Babel, um die erforderlichen Dateien zu generieren.
  • Geben Sie Übersetzungen für die Strings ein.
  • Erstellen der übersetzten Dokumentation mit Sphinx
  • Führen Sie zum Übernehmen der Änderungen ein Commit durch.

LEISTUNG 5 [Woche 9–10]: Dokumentation der Module vorbereiten. Wie mit den Mentoren besprochen, plane ich, die Moduldokumentation in zwei Teilen vorzubereiten.

Teil - I: Erstellen von Dateien in der Nähe der Module mithilfe eines Skripts, das nach gültigen Optionen aus der Codebasis sucht und deren einzeilige Verwendung (und Standardwerte) aus den entsprechenden Wiki-Seiten extrahiert. Dies würde als einfacher Entwurf dienen.

Teil II: Plattformspezifische Struktur erstellen, die alle Module, Plug-ins und Optionen für eine bestimmte Plattform (Windows und, wenn die Zeit es zulässt, auch für Fedora) verknüpft.

Wenn Sie Dateien in der Nähe der Module erstellen, ist die Dokumentation nah am Quellcode. Mit einem Bottom-Up-Ansatz wird die Hauptdokumentation der Module durch Kombinieren der Dateien aus Teil I erstellt und die Struktur aus Teil II als Referenz verwendet.

Die durch die Automatisierung erstellten Dateien müssen überprüft werden, aber die erste Priorität besteht darin, ein funktionsfähiges Framework zu erstellen. Sobald das geschehen ist, werde ich die Dateien entsprechend der verfügbaren Zeit prüfen, um die Optionen zu überprüfen. Das Framework wird priorisiert, sobald es verfügbar ist. Die Entwickler und Administratoren können ebenfalls einen Beitrag leisten, indem sie relevante Anwendungsfälle hinzufügen.

BONUSLEISTUNGSANGABE [Woche 11]: Vorbereitung auf die Veröffentlichung von Version 4.0. Falls das Projekt wie geplant abläuft, würde ich Ihnen ein zusätzliches Arbeitsergebnis anbieten. Wie bereits mit den Mentoren besprochen, setzt die Vorbereitung auf Version 4.0 voraus, dass die Dokumentation für Version 3.0 stabil und fast vollständig ist.

Daher würde ich die bereits fertiggestellte Dokumentation der folgenden Abschnitte durchgehen, um die genannten Methoden zu überprüfen und zu aktualisieren:

  • Grundlegende Verwendung: Medien, Wiedergabe, Audio, Video, Untertitel, Hotkeys, Aufnahmen, Einstellungen, Tipps und Tricks
  • Erweiterte Verwendung: Player, Benutzeroberfläche, Transcodierung, Streaming, ungewöhnliche Fälle.
  • Add-ons: Erweiterungen, Skins.

Woche 12: Pufferwoche für die oben genannten drei Liefergegenstände + Abschlussberichte.

WARUM BIN ICH DIE RICHTIGE PERSON FÜR DIESES PROJEKT?

Als Technikliebhaber habe ich Erfahrung mit der Nutzung bzw. dem Testen von Software und manchmal versuche ich, aus der Codebasis einen Sinn zu ergeben. Als ich versuchte, die Codebasis einer Open-Source-Organisation zu verstehen, war mir zum ersten Mal klar geworden, wie wichtig die Dokumentation ist. Außerdem habe ich als Musikfan viel Erfahrung mit dem VLC-Player.

Außerdem bin ich mein ganzes Leben lang Forscher und Autor gewesen. Wenn ich etwas nicht aufschreibe, verstehe ich es nie wirklich. Diese Gewohnheit hat mich zu einer effizienten Notizschreiberin und Dokumentarin gemacht.

Die Schnittmenge dieser beiden Gewohnheiten macht mich für die technische Dokumentation geeignet. Ich kann die technischen Aspekte durchgehen und meine Ergebnisse/Prozesse so dokumentieren, dass es für Nutzer verständlich ist.

Links: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35