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:
- SciPy
- Technischer Redakteur:
- mkg33
- Projektname:
- Nutzerorientierte Dokumentation und gründliche Neustrukturierung
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Motivation:
Ich habe vor, die vorhandene Dokumentation so zu refaktorieren, dass sie für Nutzer mit unterschiedlichen Anforderungen leicht zugänglich ist. Selbstverständlich interessieren sich Forschende höchstwahrscheinlich für erweiterte und subtile Funktionen, während Nutzende ohne Vorkenntnisse Schritt-für-Schritt-Anleitungen und Diagramme schätzen.
Ich möchte dieses Projekt aus persönlichen und beruflichen Gründen weiterverfolgen: Zunächst möchte ich einen erheblichen Beitrag zu SciPy leisten, weil meine eigene Forschung enorm davon profitiert hat. Zweitens stoße ich zu oft auf unzureichende (oder mangelnde) Dokumentationen in anderer Software und frage mich, wie viel schneller (wenn alles!) Nutzende mit einer ausführlichen Anleitung die Verwendung des Codes erlernen könnten.
Zielvorhaben:
Ich möchte die vorhandene SciPy-Dokumentation sowohl inhalts- als auch grafisch verbessern. Das wichtigste Merkmal meiner Herangehensweise an dieses Problem ist die Bereitstellung und Analyse der Nutzerumfrage, also eine kurze Online-Umfrage, in der verschiedene Nutzende ihre Bedürfnisse in Bezug auf die Dokumentation äußern können. Ich bin fest davon überzeugt, dass ihre Meinungen als Inspirationsquelle dienen sollten. (Wie können wir sonst eine nutzerfreundlichere Dokumentation erstellen?)
Was die Umsetzung des Projekts angeht, umfasst die erste Phase die Gestaltung und Analyse der Nutzerumfrage sowie die Lösung einiger stilistischer Probleme, die ich in der aktuellen Dokumentation festgestellt habe. Zum Beispiel: fehlende Einheitlichkeit (z. B. zweidimensionale Arrays neben zweidimensionalen Arrays), verschränkte Sätze, die umgeschrieben werden sollten, oder fehlende alphabetische Reihenfolge auf bestimmten Unterseiten. Die zweite Phase konzentriert sich auf die Einführung grafischer Leitfäden mit Hyperlinks zu den relevanten Themen (basierend auf den Umfrageergebnissen und anderen Anfragen aus der Community). Langfristig möchte ich eine zufriedenstellende Dokumentation erreichen, die auf verschiedene Arten von Nutzern zugeschnitten ist. Außerdem werde ich versuchen, die Anleitungen sowohl sprachlich als auch strukturell einheitlicher zu gestalten. Zu guter Letzt möchte ich auch neue Anleitungen schreiben (basierend auf den aktuellen Anforderungen der Community).
Nutzerumfrage:
Im Hinblick auf die Nutzerumfrage schlage ich vor, aus verschiedenen Gründen Google Formulare zu verwenden. Erstens ist Google Formulare kostenlos und bietet unbegrenzte Funktionalität (in Bezug auf die Anzahl der Befragten, Fragen usw.), es hat eine ansprechende visuelle Form, die nützlichsten Umfrageoptionen (z. B. die anpassbare lineare Skala, Kästchen und Multiple-Choice) und vor allem können die Ergebnisse einfach für statistische Analysen exportiert werden. Online-Recherchen haben ergeben, dass Google Formulare – zumindest vorerst – das beste kostenlose Tool zum Durchführen von Umfragen ist. Eine weniger ernst zu nehmende Anmerkung: Es wäre eine nette Geste, ein Google-Produkt in einer von Google geleiteten Initiative zu verwenden.
Ich habe eine vorläufige Umfrage mit Beispielfragen erstellt (Sie finden sie unter https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). Eine angemessene Anzahl von Fragen in der endgültigen Version sollte zwischen zehn und fünfzehn liegen. Um konkrete Ergebnisse zu erhalten, schlage ich vor, dass wir in erster Linie Multiple-Choice-Fragen, eine lineare Skala und einige Kontrollkästchen verwenden. Die lineare Skala sollte jedoch nicht dem gesamten Spektrum ähneln (es führt nur zu Verwirrung und die Ergebnisse leiden wahrscheinlich unter einer hohen Streuung). Es dürfen höchstens zwei offene Fragen gestellt werden. Andernfalls sind die Ergebnisse sehr verstreut und sind überhaupt nicht hilfreich. Ich glaube, selbst eine sehr hohe Anzahl von Antworten wäre kein Problem, da sich die Daten einfach exportieren und mit einer Statistiksoftware automatisch analysieren lassen. Wenn wir davon ausgehen, dass die Anzahl der Antworten sehr hoch ist, könnte die Analyse offener Fragen etwas zeitaufwändig sein, aber ich nehme an, dass sie nicht überwältigend sein wird. Schließlich schreiben Nutzende in der Regel keine Aufsätze über den Status der Dokumentation. Im schlimmsten Fall können einige Antworten einfach für spätere Analysen gespeichert werden.
Grafische Leitfäden:
Meine Vision von grafischen Leitfäden (die als Navigationstools dienen sollen) basiert auf einer weitverbreiteten Annahme, dass die meisten Menschen einfache visuelle Strukturen besser verarbeiten können als rein textbasierte Informationen. Darüber hinaus ist ein thematisch orientiertes Diagramm mit Linien, die ähnliche Interessengebiete miteinander verbinden, zweifellos ein sehr wertvolles Hilfsmittel für weniger erfahrene Nutzer (und nicht nur).
Was die Implementierung angeht, empfehle ich die Verwendung des TikZ-Pakets. Zunächst einmal ist es ein leistungsstarkes Tool, das voraussichtlich nicht bald eingestellt wird. Außerdem bietet es hochwertige Ergebnisse, eine sehr solide Dokumentation und ist ein häufiges Thema auf TeX StackExchange und anderen Mainstream-Foren. Am wichtigsten ist jedoch, dass die Integration einer TikZ-Datei (genauer gesagt der darin enthaltenen Hyperlinks) in die HTML-Dokumentation offenbar keine nennenswerten Probleme darstellt, da verschiedene Pakete und Korrekturen für das Einbetten eines TikZ-Bilds in HTML vorhanden sind (z. B. TeX4ht).
Die Frage, ob die Anleitungen in SciPy künftig gepflegt werden sollen, kann beispielsweise mithilfe von Overleaf (erleichtert die Zusammenarbeit und bietet eine Vorschau) und vordefinierten Vorlagen, die ich zur Verfügung stelle, einfach gelöst werden. Im Grunde genommen besteht die Wahrscheinlichkeit, dass sich die grafischen Übersichten nicht wesentlich voneinander unterscheiden. Struktur, Farbpalette und Formen sind mehr oder weniger unveränderlich. Eine spätere Umformung und weitere Anpassung sind daher kein Problem.
(Sie finden die vollständige Version des Vorschlags im freigegebenen GSoD-Ordner.)