VLC-Projekt

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:
VLC
Technischer Redakteur:
Avii
Projektname:
VLC-Nutzerdokumentation für einen mobilen Port (Android) erstellen
Projektlänge:
Standardlänge (3 Monate)

Projektbeschreibung

ABSTRACT

Die Nutzerdokumentation dient als statisches Supportsystem zur Unterstützung von Endnutzern. Sie enthält sowohl technische als auch nicht technische Informationen zu einem Produkt oder einer Dienstleistung. Sie hilft Nutzern, die Software oder den Dienst zu verwenden. Nicht jeder Nutzer möchte den Support kontaktieren oder auf eine E-Mail-Antwort warten, wenn er nur ein paar Hinweise, Tipps oder Tricks benötigt. Genau das tut die Nutzerdokumentation. Außerdem werden dadurch die Supportkosten gesenkt und es ist ein Indikator für den Zustand des Produkts und des Entwicklerteams.

VLC für Android wurde allein im Google Play Store über 100 Millionen Mal heruntergeladen. VLC bietet viele Funktionen für seine mobilen Ports, von der Audio- und Videowiedergabe bis hin zum Netzwerkstream. Oft möchten Nutzer diese tollen Funktionen nutzen, können dies aber nicht. Die Suche nach einem Blog oder einem zufälligen Video erfordert viel Zeit und Geduld. Außerdem ist die Authentizität der erhaltenen Informationen nicht gesichert. Derzeit hostet VLC die VLC for Android-Nutzerdokumentation auf der Wiki-Seite und bietet nur eine geringe oder gar keine Beschreibung dieser Funktionen. Außerdem wurden die Wikiseiten zuletzt im März 2019 aktualisiert. Das aktuelle Projekt wird eine neue Nutzerdokumentation mit einem modernen Design und einer höheren Nutzerfreundlichkeit für den Android-Port bereitstellen.

AKTUELLE SITUATION

Die Wiki-Seiten sind völlig veraltet und enthalten nur sehr wenige Informationen zur neuesten Version von VLC. Außerdem sind sie nicht einfach zu bedienen. Es gibt keine sichtbare Option, die Dokumentation in einer anderen Sprache als Englisch zu lesen. Es enthält überhaupt keine Funktionsbeschreibungen.

ANALYSE

-> Die aktuelle Dokumentation ist veraltet und muss neu geschrieben werden. Dabei müssen auch eine andere Plattform und andere Tools verwendet werden.

-> Die meisten Android-Nutzer verfügen über wenig oder gar keine technischen Kenntnisse. Es gibt jedoch Personen, die mehr technische Informationen zu einer Funktion benötigen. Es ist nicht sinnvoll, für jeden der oben genannten Zwecke zwei separate Dokumentationen zu erstellen und zu pflegen. Oder die Trennung einer Funktion nach technischen und nicht-technischen Fragen in der gleichen Dokumentation führt zu zusätzlicher Verwirrung. Da die meisten Nutzer mit der Benutzeroberfläche oder den Funktionen vertraut sind, ist es nicht einfach, zu entscheiden, ob etwas technisch oder nicht technisch ist. Daher sollten wir das für sie vereinfachen.

-> Die meisten Nutzer werden versuchen, Informationen über ihr Smartphone und den Computer oder andere Geräte zu erhalten. Die Dokumentation sollte daher leicht an jede Bildschirmgröße angepasst werden können. und darf keine Verwirrung bei der Navigation stiften.

-> Nicht alle Funktionen der Desktopversion sind in der Android-Version verfügbar und funktionieren, falls verfügbar, nicht auf beiden Plattformen gleich. Das liegt daran, dass Desktopanwendungen schon viel länger in der Entwicklung sind und eine Art Sättigung erreicht haben. Im Gegensatz dazu ist die mobile Version relativ neu und befindet sich noch in der Entwicklung. Darüber hinaus sind Mobilgeräte zwar heutzutage so leistungsstark, aber es gibt offensichtliche Einschränkungen im Hinblick auf die Art der Funktionen, die wir integrieren können. Dies liegt vor allem an der Nachfrage der Endanwendenden. Eine Funktion, die niemand verwendet, ist eine Verschwendung von Entwicklungsressourcen. Daher wird nicht empfohlen, beide Dokumentationen anhand von Funktionen zu vergleichen.

Basierend auf der obigen Analyse schlage ich Folgendes vor. 1. Derzeit wird für die Dokumentation für Desktopnutzer der Sphinx-Dokumentationsgenerator und das Read the Docs-Design verwendet. Die Verwendung derselben für den Android-Port bietet folgende Vorteile: -> Einfache Zusammenführung der beiden Dokumentationen. -> Sie ist für alle Bildschirmgrößen optimiert. -> Nahtlose Navigation zur Android-Nutzerdokumentation über die Desktopdokumentation

  1. Trennen Sie die Kapitel, Abschnitte und Unterabschnitte entsprechend ihrer relativen Position in der Anwendung. Beispiel: Der Hintergrund-/PiP-Modus befindet sich unter „Mehr“ -> „Einstellungen“ -> „Video“. Die Kapitelstruktur sieht dann so aus:
    Mehr
    |__Einstellungen
    | |__Mediathek
    | |__Video --> Hintergrund-/PiP-Modus
    : -> Dieser Ansatz verbessert die Barrierefreiheit, da Nutzer den Teil, in dem sie Hilfe benötigen, leicht finden können, indem sie ihn mit dem relativen Standort in der Anwendung vergleichen. Für jede der Funktionen können wir technische und nicht technische Teile weiter trennen. Wir verfassen zuerst eine einfache, nicht technische Beschreibung und markieren oder beschriften dann direkt darunter gegebenenfalls technische Teile derselben Funktion. Das kann zu Wiederholungen führen, sorgt aber dafür, dass die meisten Nutzer, die keine technischen Experten sind, problemlos zurechtkommen. Dies trägt auch dazu bei, die Wartbarkeit zu verbessern. Da die Anwendung den Sättigungszustand erreicht, wird sich die relative Benutzeroberfläche wahrscheinlich nicht wesentlich ändern. Wenn also in Zukunft eine neue Funktion hinzugefügt oder entfernt wird, können wir den Abschnitt einfach neu strukturieren. Falls sich die gesamte Benutzeroberfläche ändert, können wir die Abschnitte/Kapitel neu anordnen oder das gesamte Dokument neu strukturieren. In beiden Fällen müssen wir die gesamte Dokumentation ändern, da die Screenshots ersetzt werden müssen, um der aktuellen Benutzeroberfläche zu entsprechen. Eine funktionierende Demo wird hier gehostet : https://avinal.gitlab.io/vlc-android-docs/

  2. Jeder Abschnitt der Dokumentation muss einen beschrifteten Screenshot , eine Beschreibung der Funktion, einen technischen Teil (falls zutreffend) sowie Tipps und Tricks zur Funktion enthalten.

-> Die unabhängige Entwicklung dieser Nutzerdokumentation über den Desktop hilft uns dabei, beide Dokumentationen in nur wenigen Schritten zusammenzuführen, ohne dass die aktuelle Dokumentation beeinträchtigt wird oder während der Entwicklung davon beeinflusst wird. Ich schlage vor, diese gesamte Dokumentation nach der Entwicklung in den Android-Abschnitt der Desktop-Dokumentation zu stellen und dann einen Direktlink zur VLC-Dokumentation für Android zu erstellen.

-> Weitere Verbesserungen könnten beinhalten, die Startseite der Desktop-Nutzerdokumentation neu zu gestalten, damit Nutzer ihr bevorzugtes Betriebssystem direkt auswählen können, und den Nutzer dann zur Dokumentation des jeweiligen Betriebssystems weiterleiten. Da die Nutzerdokumentation für Windows, MacOS und Linux bereits gut gestaltet und umgangen ist, können Sie zwischen Windows/MacOS/Linux oder Android oder iOS wählen. Das führt zu einer gut getrennten, aber einheitlichen Nutzerdokumentation mit nur einem Link, der für alle Ports verwendet werden kann.

WARUM IST MEINE VORGESCHLAGENE NUTZERDOKUMENTATION BESSER? Diese vorgeschlagene Nutzerdokumentation ist auf der Grundlage gängiger Muster aufgebaut, die von den Endnutzern ausgeführt werden, um Hilfe zu erhalten. Die Dokumentation vereint alle erforderlichen Funktionen, z.B. Einfachheit, Klarheit, Erscheinungsbild und technisches Wissen, um die Nutzerfreundlichkeit zu maximieren. Dies ist auch leicht zu verwalten, da für jeden Anschluss keine separate Nutzerdokumentation mehr erforderlich ist.

WARUM BIN ICH DIE RICHTIGE PERSON FÜR DIESES PROJEKT? -> Ich schreibe jetzt seit 2 Jahren Codes und muss oft die API-Dokumentation für bestimmte Bibliotheken oder Software durchgehen oder sogar meinen eigenen Code dokumentieren. Ich weiß also genau, was die Nutzer in der Dokumentation sehen möchten, welches Problem sie haben und wie sie Hilfe erhalten. Ich kann diese Erfahrung auch auf die Erstellung einer einheitlichen und leicht lesbaren Dokumentation anwenden.

–> Ich habe aktiv technische Inhalte auf Quora, Stack Overflow und verschiedenen anderen Plattformen veröffentlicht. Ich kann Dinge auf eine einprägsame und leicht verständliche Weise erklären.

-> VLC for Android ist ein leistungsstarkes und sehr bekanntes Tool, wobei die meisten Funktionen entweder unbekannt sind oder keine Hilfe verfügbar ist. Ich nutze VLC seit vielen Jahren sowohl auf Desktop- als auch auf mobilen Plattformen und weiß, mit welchen Problemen Nutzende konfrontiert sind. Mit meinem Wissen und meiner Erfahrung kann ich eine gute Dokumentation erstellen.