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:
- VLC (VLC)
- Technischer Redakteur:
- Abhishek Pratap Singh
- Projektname:
- Modernisierung der VLC-Nutzerdokumentation fortsetzen
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
AKTUELLER STATUS DER DOKUMENTATION
Die VLC-Nutzerdokumentation wird gerade modernisiert und aktualisiert. Die Umstellung erfolgt von der Wiki-basierten älteren Dokumentation[1] zur von Sphinx entwickelten modernen Nutzerdokumentation[2], die auf ReadTheDocs gehostet wird.
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 auch für Entwickler hilfreich, da sie als einfacher Leitfaden dienen. Daher möchte ich sowohl GUI-basierte Anleitungen (zusammen mit Bildern, falls relevant) als auch CLI-basierte Methoden (zusammen mit Code-Snippets) einbinden, damit der Endnutzer eine freie Wahl hat.
Ich bin der Meinung, dass die Sprache der Dokumentation (insbesondere der GUI-Abschnitt) so betont sein sollte, dass Personen, die normalerweise nur mit Computern arbeiten, den Leitfaden verstehen und umsetzen können. Andererseits sollte es nicht zu lang oder erklärend sein (insbesondere im CLI-Abschnitt), dass die Programmierer das Interesse verlieren.
Die richtige Balance kann erreicht werden, indem die Voraussetzungen am Anfang der Seite erwähnt oder optionale Abschnitte belassen werden, die versierte Nutzer überspringen können.
Die Zielgruppe für die Erstellung von Übersetzungen sind Entwickler/Nutzer von VLC, die gut Englisch und die Sprache beherrschen, in die übersetzt werden soll.
TOOLS
Die neue Dokumentation wird von Sphinx erstellt und auf ReadTheDocs gehostet, und das Versionskontrollsystem ist in GitLab implementiert. Ich hatte einige Erfahrungen mit Git und GitHub, was mir dabei geholfen hat, mich mit GitLab vertraut zu machen. Allerdings gab es bestimmte andere Funktionen, die einige Zeit in Anspruch genommen haben.
Was Sphinx betrifft, so hatte ich auch schon davon gelesen, als ein anderer Open-Source-Enthusiast anmerkte, wie viele Unternehmen es zum Erstellen ihrer Dokumentation verwenden (wie z. B. Blender, das Sphinx für die Erstellung von Benutzerhandbüchern[3] und API-Dokumentation[4] verwendet).
Ich war gut mit ReadTheDocs vertraut, einem guten Tool für die Versionsverwaltung und das Hosten technischer Dokumentation. So konnte ich eine VLC-Dokumentation ohne große Probleme erstellen und bin mit restrukturiertem Text, der verwendeten Formatierung, vertraut.
Für Übersetzungen verwendet VLC Babel, um PO-Dateien zur Implementierung von i18n und l10n zu generieren. Derzeit mache ich mich mit dem Babel-Workflow und der Erstellung von MO-Dateien mit Sphinx vertraut.
Ich beabsichtige, die Bindungsphase zu nutzen, um mich mit den Feinheiten der oben genannten Tools vertraut zu machen.
LIEFERBARKEITEN UND WÖCHENTLICHER ZEITPLAN
Im Rahmen des Projekts von 2019 wurden bereits Teile der Installation, Schnittstelle, Audio, Video, Wiedergabe usw. (die meisten grundlegenden Funktionen) behandelt. Daher möchte ich für das Projekt 2020 den Abschnitt zur erweiterten Nutzung der Nutzerdokumentation aktualisieren und daran arbeiten.
LIEFERBARE 1 [Woche 1–2]: Aktualisieren Sie die Transcode-Dokumentation, wie in Nr. 7[5] erwähnt.
- Transcodieren
- Mehrere Videos transcodieren
- Logo hinzufügen
- Videos zusammenführen
- Audio und Audio aus einer Datei extrahieren
- DVD rippen
LIEFERBARE 2 [Woche 3–4]: Update mit VLC als Web-Plug-in[6] durchführen (Tests in Firefox 77, Chrome 83 und Edge 83)
- Webseiten mit Videos erstellen
- Embed-Tag-Attribute
- JavaScript API-Beschreibung
LIEFERUNG 3 [Woche 5]: Testen Sie die Befehle der Befehlszeile[7] und aktualisieren Sie sie entsprechend.
- Streams
- Modulauswahl
- Artikelspezifische Optionen
- Filter
Woche 6: Pufferwoche für die drei oben genannten Liefergegenstände.
LIEFERUNG 4 [Woche 7–8]: Übersetzungen vorbereiten. Neben der Aktualisierung bereite ich Übersetzungen in andere Sprachen vor. Das ist wichtig, da Nutzer ohne englischsprachigen Hintergrund nach der Übersetzung die Dokumentation lesen können (und nebenbei wäre der 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 werde den Prozess für einen Nutzer/Freiwilligen dokumentieren, um:
- Basisdokumentation herunterladen und lokal erstellen
- Verwenden Sie Babel, um die erforderlichen Dateien zu generieren.
- Geben Sie Übersetzungen für die Strings ein.
- Erstellen der übersetzten Dokumentation mit Sphinx.
- Übernehmen Sie die Änderungen.
LIEFERBARE 5 [Woche 9–10]: Bereiten Sie sich auf die Dokumentation zu den Modulen vor. Wie mit den Mentoren besprochen, plane ich die Vorbereitung der Moduldokumentation in zwei Teilen.
Teil - I: Erstellen von Dateien in der Nähe der Module mithilfe eines Skripts, das aus der Codebasis nach gültigen Optionen sucht und deren einzeilige Nutzung (sowie Standardwerte) von den entsprechenden Wiki-Seiten extrahiert. Dies dient als Basisentwurf.
Teil - II: Eine plattformspezifische Struktur erstellen, die alle Module, Plug-ins und Optionen für eine bestimmte Plattform verknüpft (Windows und, wenn es die Zeit erlaubt, auch für Fedora).
Durch das Erstellen von Dateien in der Nähe der Module wird sichergestellt, dass sich die Dokumentation nah am Quellcode befindet. Mit einem Bottom-top-Ansatz besteht die Hauptdokumentation zu Modulen aus der Kombination der in Teil I erstellten Dateien und der Verwendung der in Teil II erstellten Struktur als Referenz.
Die automatisch erstellten Dateien müssten überprüft werden, aber die erste Priorität ist es, ein funktionierendes Framework zu erstellen. Sobald dies erreicht ist, und wie viel Zeit verfügbar ist, würde ich die Dateien überprüfen, um die Optionen zu überprüfen. Das Framework wird priorisiert, da sobald es verfügbar ist, können auch die Entwickler und Administratoren einen Beitrag leisten, indem sie relevante Anwendungsfälle hinzufügen.
BONUSVERÖFFENTLICHUNG [Woche 11]: Bereite dich auf das Release 4.0 vor. Für den Fall, dass das Projekt im Zeitplan bleibt, möchte ich einen Bonus als Liefergegenstand vorschlagen. Wie mit den Mentoren besprochen, setzt die Vorbereitung auf die Version 4.0 voraus, dass eine stabile und nahezu vollständige Dokumentation für Version 3.0 vorliegt.
Daher werde ich die bereits ausgefüllte 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 Nutzung: Player, Schnittstelle, Transcodierung, Streaming, ungewöhnliche Fälle.
- Add-ons: Erweiterungen, Skins.
Woche 12: Pufferwoche für die drei oben genannten Liefergegenstände + Abschlussberichte.
WARUM bin ICH DIE RICHTIGE PERSON FÜR DIESES PROJEKT?
Als Technikfan habe ich Erfahrung mit der Verwendung/Tests von Software und manchmal versuche ich, auf der Codebasis Sinn zu ergeben. Tatsächlich war der Versuch, die Codebasis einer Open-Source-Organisation zu verstehen, das erste Mal, dass ich die Bedeutung der Dokumentation erkannt hatte. Außerdem habe ich als Musikfan viel Erfahrung mit der Optimierung von VLC :)
Abgesehen davon war ich mein ganzes Leben lang Forscher und Autorin. Wenn ich nichts aufschreibe, verstehe ich es nie wirklich, und diese Gewohnheit hat mich zu einer effizienten Journalistin und Dokumentiererin gemacht.
Aufgrund der Schnittmenge dieser beiden Gewohnheiten bin ich der ideale Kandidat für technische Dokumentation. Ich kann mich mit den technischen Aspekten vertraut machen und meine Ergebnisse/Prozesse so dokumentieren, dass die Nutzenden sie verstehen.
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/index5