Toss veröffentlicht Leitfaden für Technical Writing

Kernprinzipien für das Schreiben guter technischer Dokumentation

1. Den Dokumenttyp festlegen

Je nach Zweck des Dokuments gibt es unterschiedliche, effektivere Wege zu schreiben.

• Lernorientierte Dokumentation: dient dazu, den Ablauf zu verstehen, wenn man zum ersten Mal mit einer neuen Technologie oder einem neuen Tool in Berührung kommt
• Problemlösungsdokumentation: dient dazu, ein bestimmtes Problem zu lösen, wenn bereits Hintergrundwissen vorhanden ist
• Referenzdokumentation: dient dazu, die Nutzung einer bestimmten Funktion oder API nachzuschlagen, wenn man die grundsätzliche Verwendung bereits kennt
• Erklärende Dokumentation: dient dazu, Konzepte, Prinzipien und Hintergrundwissen im Detail zu verstehen

2. Eine Informationsstruktur erstellen

Neue Kenntnisse zu verstehen erfordert zwar Aufwand, aber durch die Strukturierung von Informationen lässt sich dieser Aufwand verringern.

• Pro Seite nur ein Thema behandeln
• Zuerst den Mehrwert liefern
• Effektive Überschriften schreiben
• Eine Übersicht nicht weglassen
• Vorhersehbarkeit schaffen

3. Sätze überarbeiten

Wenn die Aussagekraft von Sätzen verbessert wird, können Leser die Inhalte leichter verstehen. Werden Details in schwer verständlichen Sätzen ausgedrückt, leidet die Verständlichkeit erheblich.

• Das Subjekt des Satzes klar machen
• Nur die notwendigen Informationen stehen lassen
• Konkret schreiben
• Natürliche koreanische Formulierungen verwenden
• Konsistent schreiben

[tested]

Gibt es keinen Ort, an dem solche von Toss erstellten Websites gesammelt werden?

[dontdieych]

Mit dem -yo-Stil kann ich mich nur schwer anfreunden.

[gera1d]

Das stimmt.

[winterjung]

Gefällt mir. Vor allem den Teil zur Überarbeitung von Sätzen würde ich gern als few-shot mit GPTs bauen und verwenden.

[mathgig]

Solche Texte finde ich gut. Wie könnten sich solche Richtlinien im Zeitalter der LLMs verändern?

[bluejoyq]

Das ist wirklich ein großartiges Projekt. ^^