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:
- HPX
- Technischer Redakteur:
- Rstobaugh
- Projektname:
- Vorhandene HPX-Dokumentation bearbeiten und optimieren
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Mein Vorschlag ist, den Inhalt der vorhandenen HPX-Dokumentation zu bearbeiten und zu optimieren. Mein Vorschlag betrifft ein dreimonatiges Projekt mit Standardlaufzeit, das sich auf die Überarbeitung von zwei Kapiteln des Handbuchs der STE||AR-Gruppe konzentriert: „„HPX Build System and Launching“ (1) und „Konfigurieren von HPX-Anwendungen“ (2).
Das Kapitel „HPX Build System and Launching“ enthält mehrere Grammatikfehler und eine verwirrende Sprache und uneinheitliche Großschreibung von Begriffen wie „CMake“. Außerdem enthält es sich wiederholende Informationen, die ich nach Bedarf neu anordnen, zusammenfassen und kürzen möchte. Während das Kapitel „„Konfigurieren von HPX-Anwendungen““ auch einige Grammatikfehler enthält, die behoben werden müssen, ist mein Hauptanliegen dieses Kapitels seine Benutzerfreundlichkeit. Das Kapitel hat drei wichtige Designprobleme, die ich angehen möchte:
Einige Überschriften sind im Text verborgen, was das Überfliegen des Kapitels erschwert. Derzeit muss ein Nutzer das Handbuch sorgfältig durchlesen, um den Zweck der einzelnen Tabellen zu verstehen. Dies entspricht nicht der Art und Weise, wie die meisten Nutzer mit Bedienungsanleitungen umgehen, insbesondere wenn sie sich die Inhalte bereits zuvor durchgelesen haben. Stattdessen möchte ich sicherstellen, dass jede Tabelle eine klare, eindeutige Überschrift hat, die leicht erkennbar ist, wenn Nutzende durch den Text scrollen.
Beim Auflisten verschiedener Unterkünfte unter einer bestimmten Überschrift folgen die Eigenschaften keiner logischen Reihenfolge. Unterkünfte sind zwar unter einem gemeinsamen Thema gruppiert, es gibt jedoch keine Untergruppen, sodass die Informationen verstreut wirken. Ein Nutzer kann beispielsweise auf mehrere Properties stoßen, die sich mit Lokalität befassen, einige, die sich mit einem anderen Thema befassen, und dann einer anderen, die sich mit dem Ort befasst. Da die interne Struktur unter Überschriften fehlt, ist es schwieriger, alle Informationen zu einem bestimmten untergeordneten Thema zu finden. Daher habe ich vor, mehrere Diagramme neu anzuordnen, um ähnliche Informationen unter den einzelnen Überschriften besser zusammenzufassen.
Nutzer müssen zwischen den Abschnitten hin und her navigieren oder das Handbuch in zwei separaten Tabs öffnen, um bestimmte Anweisungen vollständig zu verstehen. Es gibt Punkte, an denen das Kapitel die Nutzenden in einer Weise zu einem einzelnen Satz in einem vorherigen Abschnitt leitet, dass der Lesende nach oben scrollen oder einem Hyperlink folgen muss, um die genaue Anleitung zu verstehen, da im Handbuch vage Formulierungen wie „Dieser Schritt wird nach Schritt 11 vorformuliert“ im vorherigen Abschnitt verwendet. Bei dieser Methode werden Wiederholungen vermieden, die Anweisungen werden jedoch schwieriger verständlich, da es sich hierbei um Aufgaben handelt, die in einer bestimmten Reihenfolge ausgeführt werden müssen. Stattdessen schlage ich vor, konkretere Formulierungen zu verwenden, damit Nutzende ihren Leseprozess nicht durch Wechseln zwischen Abschnitten oder Dokumenten unterbrechen müssen.
Wenn ich diese Abschnitte ausfülle, bevor die Standardzeitachse vollständig ist, möchte ich auch die Seite „Why HPX?“ (3) in der Benutzerdokumentation der STE||AR-Gruppe aufräumen. Diese Seite enthält sich wiederholende einführende Inhalte, die ich gerne zusammenfassen möchte. Außerdem enthält sie Uneinheitlichkeiten in der Groß-/Kleinschreibung (insbesondere im Fachjargon) und im Ton, die der Einheit einen uneinheitlichen Eindruck verleihen. Mein Ziel wäre es, eine einheitlichere, einheitlichere Einführung in die Arbeit der STE||AR-Gruppe zu schaffen.