Diese Seite enthält die Details zu einem Projekt für technische Angelegenheiten, das für die Google-Saison der Dokumente angenommen wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- SciPy
- Technischer Redakteur:
- mkg33
- Projektname:
- Nutzerorientierte Dokumentation und gründliche Umstrukturierung
- Projektlänge:
- Standardlänge (3 Monate)
Projektbeschreibung
Motivation:
Ich beabsichtige, die vorhandene Dokumentation zu überarbeiten, damit sie für Nutzer mit unterschiedlichen Anforderungen leicht zugänglich ist. Es versteht sich von selbst, dass sich ein Rechercheur höchstwahrscheinlich für erweiterte und subtile Funktionen interessiert, während ein Nutzer ohne Vorkenntnisse Schritt-für-Schritt-Anleitungen und Diagramme schätzt.
Ich möchte dieses Projekt aus persönlichen und beruflichen Gründen verfolgen: Erstens möchte ich einen wesentlichen Beitrag zu SciPy leisten, da meine eigene Forschung davon stark profitiert hat. Zweitens stoße ich bei anderen Softwarelösungen allzu oft auf unzureichende (oder fehlende) Dokumentationen und frage mich immer, wie viel schneller (wenn überhaupt!) Nutzer den Code beherrschen könnten, wenn sie eine ausführliche Anleitung hätten.
Zielvorhaben:
Ich möchte die vorhandene SciPy-Dokumentation sowohl inhaltlich als auch grafisch verbessern. Das wichtigste Merkmal meiner Herangehensweise an dieses Problem ist die Bereitstellung und Analyse der Nutzerbefragung, d. h. einer prägnanten Online-Umfrage, in der verschiedene Nutzende ihre Anforderungen an die Dokumentation äußern können. Ich bin der festen Überzeugung, dass ihre Meinungen eine Quelle der Inspiration sein sollten. Wie sonst können wir eine nutzerfreundlichere Dokumentation erstellen?
Was die Umsetzung des Projekts anbelangt, umfasst die erste Phase die Gestaltung und Analyse der Nutzerumfrage sowie die Klärung mehrerer stilistischer Probleme, die mir in der aktuellen Dokumentation aufgefallen sind. Dazu gehören beispielsweise mangelnde Konsistenz (z. B. zweidimensionale Arrays neben zweidimensionalen Arrays), unklare Sätze, die umformuliert werden sollten, oder die fehlende alphabetische Reihenfolge auf bestimmten Unterseiten. In der zweiten Phase liegt der Schwerpunkt auf der Einführung von grafischen Anleitungen mit Hyperlinks zu den relevanten Themen (basierend auf den Umfrageergebnissen und anderen Communityanfragen). Langfristig möchte ich eine zufriedenstellende Dokumentation erreichen, die auf verschiedene Arten von Nutzenden zugeschnitten ist. Außerdem werde ich versuchen, die Anleitungen sowohl sprachlich als auch strukturell einheitlicher zu gestalten. Zu guter Letzt möchte ich neue Anleitungen schreiben (basierend auf den aktuellen Anforderungen der Community).
Nutzerumfrage:
Für die Nutzerumfrage schlage ich aus mehreren Gründen Google Formulare vor. Google Formulare ist kostenlos und bietet unbegrenzte Funktionen (in Bezug auf die Anzahl der Teilnehmer, Fragen usw.), ein ansprechendes visuelles Format, 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. Onlinerecherchen haben ergeben, dass Google Formulare zumindest derzeit das beste kostenlose Tool für die Durchführung von Umfragen ist. In weniger ernstem Ton: Es wäre eine nette Geste, ein Google-Produkt in einer von Google verwalteten Initiative zu verwenden.
Ich habe eine vorläufige Umfrage mit Beispielfragen erstellt. Sie können sie unter https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform aufrufen. Die endgültige Version sollte zehn bis fünfzehn Fragen enthalten. Um konkrete Ergebnisse zu erhalten, schlage ich vor, dass wir vor allem Multiple-Choice-Fragen, eine lineare Skala und ein paar Kästchen verwenden. Die lineare Skala sollte jedoch nicht einem vollständigen Spektrum entsprechen, da dies nur zu Verwirrung führt und die Ergebnisse wahrscheinlich von einer hohen Streuung betroffen sind. Es sollten maximal zwei offene Fragen gestellt werden, da die Ergebnisse sonst zu weit auseinanderliegen und nicht hilfreich sind. Ich denke, dass selbst eine sehr hohe Anzahl von Antworten kein Problem darstellen würde, da die Daten einfach exportiert und mit statistischer Software automatisch analysiert werden können. Angenommen, die Anzahl der Antworten ist tatsächlich sehr hoch, kann die Analyse der offenen Fragen etwas zeitaufwendig sein, aber ich gehe davon aus, dass sie nicht überwältigend ist. Schließlich ist es unwahrscheinlich, dass ein durchschnittlicher Nutzer einen Essay über den Zustand der Dokumentation schreibt. Im schlimmsten Fall können einige Antworten einfach für eine spätere Analyse gespeichert werden.
Grafische Anleitungen:
Meine Vision der grafischen Leitfäden (die als Navigationstools dienen sollen) basiert auf der weit verbreiteten Annahme, dass (die meisten) Menschen visuelle Strukturen besser verarbeiten können als rein textbasierte Informationen. Darüber hinaus ist ein thematisch orientiertes Diagramm mit Linien, die ähnliche Themen verbinden, zweifellos ein äußerst wertvolles Asset für weniger erfahrene Nutzer (und nicht nur).
Für die Implementierung schlage ich vor, das TikZ-Paket zu verwenden. In erster Linie ist es ein leistungsstarkes Tool, das wohl nicht bald eingestellt wird. Außerdem bietet es eine hochwertige Ausgabe, eine solide Dokumentation und ist ein häufiges Thema auf TeX StackExchange und anderen Mainstream-Foren. Vor allem die Einbindung einer TikZ-Datei (genauer gesagt der zahlreichen Hyperlinks darin) in eine HTML-Dokumentation scheint keine größeren Probleme zu verursachen, da es verschiedene Pakete und Fehlerkorrekturen zum Einbetten eines TikZ-Bildes in HTML gibt (z. B. TeX4ht).
Die Frage der zukünftigen Pflege der Anleitungen in SciPy lässt sich ganz einfach mithilfe von z. B. Overleaf (erleichtert die Zusammenarbeit und bietet eine sofortige Vorschau) und vordefinierten Vorlagen lösen, die ich zur Verfügung stellen werde. Im Grunde unterscheiden sich die grafischen Anleitungen wahrscheinlich nicht wesentlich voneinander. Struktur, Farbpalette und Formen bleiben mehr oder weniger unverändert, sodass spätere Änderungen und weitere Anpassungen kein Problem darstellen.
(Die vollständige Version des Vorschlags finden Sie im freigegebenen GSoD-Ordner.)