Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- SciPy
- Technischer Redakteur:
- mkg33
- Projektname:
- Nutzerorientierte Dokumentation und gründliche Umstrukturierung
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Motivation:
Ich beabsichtige, die vorhandene Dokumentation zu refaktorieren, damit sie für Nutzer mit unterschiedlichen Anforderungen leicht zugänglich ist. Es ist selbstverständlich, dass Forschende höchstwahrscheinlich an erweiterten und subtilen Funktionen interessiert sind, während Nutzende ohne Vorkenntnisse Schritt-für-Schritt-Anleitungen und Diagramme schätzen.
Ich bin daran interessiert, dieses Projekt aus persönlichen und beruflichen Gründen zu verfolgen: Zunächst möchte ich erheblich zu SciPy beitragen, weil meine eigene Forschung enorm davon profitierte. Zweitens stoße ich zu häufig auf unzureichende (oder mangelhafte) Dokumentation in anderer Software und frage mich immer, wie viel schneller (wenn alles!) die Nutzer mit einem detaillierten Leitfaden lernen könnten, den Code zu verwenden.
Zielvorhaben:
Ich möchte die vorhandene SciPy-Dokumentation sowohl inhalts- als auch grafikbezogen verbessern. Das wichtigste Merkmal meines Ansatzes bei diesem Problem ist die Bereitstellung und Analyse der Nutzerumfrage, d. h. eine kurze Online-Umfrage, mit der verschiedene Nutzende ihre Bedürfnisse hinsichtlich der Dokumentation äußern können. Ich bin fest davon überzeugt, dass ihre Meinungen als Inspirationsquelle dienen sollten. Wie können wir sonst noch eine nutzerfreundlichere Dokumentation erstellen?
Was die Umsetzung des Projekts angeht, umfasst die erste Phase die Gestaltung und Analyse der Nutzerumfrage sowie die Lösung verschiedener stilistischer Probleme, die ich in der aktuellen Dokumentation festgestellt habe. Zum Beispiel: fehlende Einheitlichkeit (z. B. zweidimensionale Arrays neben zweidimensionalen Arrays), komplizierte 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, die zu den aktuellen Anforderungen der Community passen.
Nutzerumfrage:
Was die Nutzerumfrage betrifft, so schlage ich vor, aus verschiedenen Gründen Google Formulare zu verwenden. Erstens ist Google Formulare kostenlos und bietet uneingeschränkte Funktionalität (in Bezug auf die Anzahl der Befragten, Fragen usw.), es hat eine ansprechende visuelle Darstellung, die nützlichsten Umfrageoptionen (z. B. die anpassbare lineare Skala, Kästchen und Multiple-Choice) und, was am wichtigsten ist, dass die Ergebnisse für statistische Analysen einfach exportiert werden können. Online-Recherchen zeigen, dass Google Formulare zumindest vorerst das beste kostenlose Tool für die Durchführung von Umfragen ist. Andererseits wäre es eine nette Geste, ein Google-Produkt in einer Google-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 finalen Version sollte zwischen zehn und fünfzehn liegen. Um konkrete Ergebnisse zu erhalten, empfehlen wir vor allem Multiple-Choice-Fragen, eine lineare Skala und einige Kästchen. Die lineare Skala sollte jedoch nicht dem gesamten Spektrum ähneln (es führt nur zu Verwirrung und die Ergebnisse leiden wahrscheinlich an einer hohen Streuung). Darf es höchstens zwei offene Fragen geben, andernfalls werden die Ergebnisse stark verstreut und überhaupt nicht hilfreich sein. Ich bin der Meinung, dass selbst eine sehr hohe Anzahl von Antworten kein Problem ist, da sich die Daten einfach exportieren und mit statistischer Software automatisch analysieren lassen. Unter der Annahme, dass die Anzahl der Antworten in der Tat sehr hoch ist, könnte die Analyse offener Fragen etwas zeitaufwändig sein, aber ich gehe davon aus, dass sie nicht überwältigend sein wird. Schließlich schreiben durchschnittliche Nutzende wahrscheinlich keine Aufsätze über den Status der Dokumentation. Im Worst-Case-Szenario können einige Antworten einfach für zukünftige Analysen gespeichert werden.
Grafische Anleitungen:
Meine Vorstellung von den 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 äußerst wertvolles Hilfsmittel für weniger erfahrene Nutzer (und nicht nur).
Was die Implementierung angeht, schlage ich vor, das TikZ-Paket zu verwenden. Zunächst ist es ein leistungsstarkes Tool, das voraussichtlich nicht bald eingestellt wird. Es bietet außerdem hochwertige Ergebnisse, eine sehr solide Dokumentation und ist ein häufiges Thema auf TeX StackExchange und in anderen Mainstream-Foren. Am wichtigsten ist jedoch, dass die Integration einer TikZ-Datei (genauer gesagt die zahlreichen darin enthaltenen Hyperlinks) in die HTML-Dokumentation offenbar keine nennenswerten Probleme darstellt, da verschiedene Pakete und Fehlerbehebungen für das Einbetten von TikZ-Bildern in HTML vorhanden sind (z. B. TeX4ht).
Die Frage, ob die Handbücher in SciPy künftig gepflegt werden sollen, lässt sich leicht lösen, indem ich zum Beispiel Overleaf (erleichtert die Zusammenarbeit und bietet eine Vorschau) und vordefinierte Vorlagen, die ich zur Verfügung stelle. Grundsätzlich unterscheiden sich die grafischen Leitfäden in der Regel nicht zu sehr voneinander. Struktur, Farbpalette und Formen sind mehr oder weniger unveränderlich, sodass spätere Umformungen und weitere Anpassungen kein Problem darstellen.
(Sie finden die Vollversion des Vorschlags im freigegebenen GSoD-Ordner.)