Technisches Schreiben
Teilen:
Diese Fragen wurden nur Befragten gestellt, die mit technischer Dokumentation befasst sind.
12% aller Befragten gaben an, sich mit technischer Redaktion zu befassen. Von diesen sind allerdings nur 10% offiziell als technische Redakteur*innen tätig.
Dies bedeutet, dass in der Entwicklungsökosystem-Umfrage 2023 von JetBrains 90% derjenigen, die Dokumentationen verfassen, sich nicht als technische Redakteur*innen verstehen. Dies führt zu Fragen bezüglich der teamübergreifenden Zusammenarbeit, der Qualität und Einheitlichkeit von Dokumentationen und der Rolle von technischen Redakteur*innen.
Daniele Procida
Technischer Direktor, Canonical
Bei der Dokumentation geht es nicht nur um technische Redaktion oder die Ergebnisse des Schreibvorgangs. Dokumentationen prägen die Beziehung der Benutzer*innen zum Produkt. Sie haben auch einen Einfluss darauf, wie das Produkt von seinen Schöpfer*innen gesehen wird – jeder, der an einem Produkt beteiligt ist, sollte über das Produkt nachdenken müssen.
Alyssa Rock
Community-Managerin, The Good Docs Project
Eines ist klar: Entwickler*innen erkennen den Wert einer guten Dokumentation (vor allem, weil sie wissen, wie lästig und schwierig es sein kann, ein schlecht dokumentiertes Tool zu verwenden). Sie wissen nur manchmal nicht, wie sie gute Dokumentation schreiben können.
Chris Chinchilla
Autor und Podcaster, chrischinchilla.com
In unserer Autorengemeinschaft führen wir endlose Diskussionen über Sprache, Werkzeuge und Methoden. Diese Zahlen zeigen jedoch, dass wir Tools, Schulungen und Community-Tipps benötigen, damit jede und jeder hochwertige Dokumentationen schreiben kann.
Die meisten Befragten arbeiten an internen und Code-Dokumentationen. Seit dem Vorjahr ist der Anteil derjenigen, die an kundenorientierten Dokumentationen arbeiten, um vier Prozentpunkte zurückgegangen.
Authoring-Tools für Dokumentationen
Anpassbare Texteditoren sind nach wie vor das Werkzeug der Wahl für das Schreiben von Dokumentationen. Sie bieten ein leichtgewichtiges, flexibles und effizientes Mittel zum Bearbeiten von Text und Code und eignen sich daher besonders gut für das Verfassen von Dokumentationen.
Allerdings ging in diesem Jahr die Nutzung von anpassbaren Texteditoren um sieben Prozentpunkte zurück, während GitHub Pages mit sechs Prozentpunkten einen fast gleich hohen Anstieg verzeichnet hat. Gleichzeitig hat Confluence, ein führender Vertreter kollaborativer Wiki-Dokumentationen, seine Position behauptet.
Von den 3% der Befragten, die eine professionelle Authoring-Lösung für Hilfedateien verwenden, bevorzugen 42% kundenspezifische Tools. Unter den verbleibenden Optionen hebt sich als einziges neueres Tool Paligo mit einem Anteil von 5% ab. Alle anderen gängigen Optionen sind traditionelle, bewährte Werkzeuge.
Zwar haben mehr als die Hälfte derjenigen, die sich mit technischer Redaktion befassen, noch nicht erwogen, ein professionelles Tool zu verwenden, aber 45% stehen dieser Idee offen gegenüber.
Markup
Markdown hat nach wie vor eine dominante Stellung. Im Vergleich zum Vorjahr ist jedoch eine deutliche Verlagerung von Standard-Markdown (minus 7 Prozentpunkte) und Markdown-Varianten (minus 4 Prozentpunkte) hin zu WYSIWYG- und Office-ähnlichen Anwendungen (plus 6 Prozentpunkte) zu beobachten. Bedeutet dies, dass die Kontrolle über die Quelldaten zugunsten von Komfort oder Benutzerfreundlichkeit in den Hintergrund tritt?
Vorlagen und Wiederverwendung von Inhalten
Fast die Hälfte der Befragten verwendet einen strukturierten Ansatz zur Wiederverwendung von Inhalten. Dennoch greifen immer noch stattliche 32% auf Copy-and-Paste zurück, möglicherweise aufgrund von Beschränkungen in den verwendeten Tools. Dies kann zu Unstimmigkeiten führen und den Dokumentationsprozess verlangsamen.
Automatisierte Prüfungen und Dokumentationsqualität
Nur 13% der Befragten verwenden automatisierte Prüfungen in der technischen Dokumentation. Die überwiegende Mehrheit schreibt ihre Tests selbst, anstatt öffentliche Linter zu verwenden, wohl weil die Tests auf fehlerhaftes Markup, Links und Referenzen abzielen. Für Sprach- und Stilprüfungen werden integrierte Rechtschreibprüfungen bevorzugt.
API-Dokumentation
Mehr als die Hälfte der Befragten schreiben API-Referenzen. Unter Entwickler*innen ist der Anteil am höchsten – 81% geben an, API-Referenzen zu schreiben. Es folgen Architekt*innen (19%), technische Redakteur*innen (18%) und DevOps-Engineers (17%). Andere Arbeitsrollen sind weniger in diese Aufgabe eingebunden, und in höheren Positionen wie CIOs, CEOs und CTOs ist nur ein geringer Prozentsatz (7%) der Befragten in diese Tätigkeit involviert.
61%
Die Mehrheit (61%) generiert API-Referenzen automatisch und direkt aus dem Code – eine Praxis, die auf effiziente Dokumentationsprozesse hindeutet. Bei den Tools dominiert Swagger mit einem Nutzungsanteil von 84%.
2/3
Etwa zwei Drittel derjenigen, die Automatisierung nutzen, finden es immer noch notwendig, ihre automatisch generierten Inhalte manuell zu optimieren. Die Automatisierung beschleunigt zwar die Basisabläufe, aber manueller Input ist entscheidend, um API-Referenzen mit Kontext zu versehen und ihnen eine persönliche Note zu geben.
Sprachen und Lokalisierung
Englisch ist nach wie vor die gängigste Hauptsprache für technische Dokumentation. Chinesisch liegt weit abgeschlagen auf dem zweiten Rang und hat in diesem Jahr vier Prozentpunkte verloren. Japanisch liegt auf dem dritten Platz und hat seit dem letzten Jahr sieben Prozentpunkte zugelegt.
Nur 14% der Befragten übersetzen ihre Dokumentation in andere Sprachen, während 8% dies erwägen. Diese Zahlen haben sich seit dem Vorjahr nicht nennenswert geändert.
Danke, dass Sie sich die Zeit genommen haben!
Wir hoffen, dass Sie unseren Bericht nützlich fanden. Teilen Sie diesen Bericht im Freundes- und Kollegenkreis.
Werden Sie Mitglied im JetBrains Tech Insights Lab
Nehmen Sie an Umfragen und UX-Studien teil, um JetBrains-Produkte benutzerfreundlicher und gleichzeitig leistungsfähiger zu machen. Durch die Teilnahme an unserer Forschung können Sie auch Prämien erhalten.
Rohdaten Demnächst verfügbar
Wir sind dabei, die Rohdaten aufzubereiten. Sie können Ihre E-Mail-Adresse hinterlassen, um benachrichtigt zu werden, wenn die Daten zum Download bereitstehen.
Wenn Sie Fragen oder Anregungen haben, schreiben Sie uns bitte unter surveys@jetbrains.com.