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:
- HPX
- Technischer Redakteur:
- rstobaugh
- Projektname:
- Vorhandene HPX-Dokumentation bearbeiten und optimieren
- Projektlänge:
- Standardlänge (3 Monate)
Projektbeschreibung
Mein Vorschlag ist, den Inhalt der vorhandenen HPX-Dokumentation zu bearbeiten und zu optimieren. Ich schlage ein Projekt mit einer Standardlaufzeit von drei Monaten vor, das sich auf die Überarbeitung von zwei Kapiteln des Handbuchs der STE||AR-Gruppe konzentriert: „HPX Build System and Launching“ (1) und „Configuring HPX Applications“ (2).
Das Kapitel zu „HPX Build System and Launching“ enthält mehrere Grammatikfehler und enthält auch verwirrende Sprache und uneinheitliche Großschreibung von Begriffen wie „CMake“. Darüber hinaus enthält es wiederholte Informationen, die ich nach Bedarf neu anordnen, konsolidieren und kürzen möchte. Das Kapitel „HPX-Anwendungen konfigurieren“ enthält zwar auch einige grammatische Fehler, die behoben werden müssen, aber mein Hauptanliegen bei diesem Kapitel ist die Nutzerfreundlichkeit. Das Kapitel enthält drei Hauptdesignprobleme, die ich angehen möchte:
Einige Überschriften sind im Text vergraben, was es schwierig macht, das Kapitel zu überfliegen. Derzeit müssen Nutzende das Handbuch sorgfältig durchlesen, um den Zweck der einzelnen Tabellen zu verstehen. So interagieren die meisten Nutzer nicht mit Anleitungen, insbesondere wenn sie den Inhalt bereits kennen. Stattdessen möchte ich dafür sorgen, dass jede Tabelle eine klare, eindeutige Überschrift hat, die leicht zu sehen ist, wenn ein Nutzer durch den Text scrollt.
Die verschiedenen Unterkünfte, die unter einer bestimmten Überschrift aufgeführt sind, folgen keiner logischen Reihenfolge. Die Unterkünfte sind zwar nach einem gemeinsamen Thema gruppiert, es gibt jedoch keine Untergruppen, was die Informationen unübersichtlich macht. Ein Nutzer kann beispielsweise mehrere Unterkünfte finden, die sich auf die Lage beziehen, einige, die sich auf ein anderes Thema beziehen, und dann eine weitere, die sich auf die Lage bezieht. Dieser Mangel an interner Struktur unter den Überschriften erschwert es, alle Informationen zu einem bestimmten Unterthema zu finden. Daher werde ich einige der Diagramme neu anordnen, um ähnliche Informationen klarer unter den einzelnen Überschriften zu gruppieren.
Nutzer müssen zwischen den Abschnitten hin- und herspringen (oder die Anleitung in zwei separaten Tabs öffnen), um bestimmte Anweisungen vollständig zu verstehen. Es gibt Stellen, an denen der Nutzer im Kapitel auf einen einzelnen Satz in einem vorherigen Abschnitt verwiesen wird, sodass er scrollen oder einem Hyperlink folgen muss, um die genaue Anleitung zu verstehen, da im Handbuch vage Formulierungen wie „Dieser Schritt wird nach Schritt 11 ausgeführt“ verwendet werden. Mit dieser Methode wird zwar die Wiederholung vermieden, aber es wird schwieriger, die Anweisungen zu verstehen, da diese Aufgaben in einer bestimmten Reihenfolge ausgeführt werden müssen. Stattdessen schlage ich vor, eine präzisere Formulierung zu verwenden, damit Nutzer ihren Lesevorgang nicht durch das Wechseln zwischen Abschnitten oder Dokumenten unterbrechen müssen.
Wenn ich diese Abschnitte vor Ablauf der Standardzeitleiste fertigstelle, würde ich auch die Seite „Warum HPX?“ (3) in der Nutzerdokumentation der STE||AR-Gruppe überarbeiten. Diese Seite enthält sich wiederholende einführende Inhalte, die ich zusammenführen möchte. Außerdem gibt es Inkonsistenzen bei der Großschreibung (insbesondere bei Fachjargon) und beim Tonfall, was den Eindruck erweckt, dass die Seite nicht einheitlich ist. Mein Ziel wäre es, eine einheitlichere, konsistentere Einführung in die Arbeit der STE||AR-Gruppe zu schaffen.