Ein Ansatz mit Fokus auf Entscheidungen statt auf Aufgaben

• Auf Entscheidungen fokussieren

  • Ein Zitat aus Every Page Is Page One führte zu einem großen Wandel im Ansatz beim Verfassen technischer Dokumentation
  • In der technischen Kommunikation spricht man meist über die Unterstützung bei Aufgaben, aber in vielen Fällen sind die Informationen, die Menschen zum Abschluss einer Aufgabe benötigen, nicht Hinweise zur Bedienung einer Maschine, sondern Informationen zur Unterstützung von Entscheidungen
  • Es reicht nicht aus, nur Verfahren zu dokumentieren
  • Man muss die Nutzer darüber informieren, welche Entscheidungen sie treffen müssen und welche Folgen diese haben, und sie möglichst zu Ressourcen und Referenzmaterialien führen, die die Entscheidungsfindung unterstützen

Zusammenfassung von GN⁺

• Dieser Artikel betont die Bedeutung der Entscheidungsunterstützung beim Verfassen technischer Dokumentation
• Es ist notwendig, über die bloße Beschreibung von Verfahren hinauszugehen und Nutzern zu helfen, bessere Entscheidungen zu treffen
• Für technische Redakteure ist es wichtig, den Nutzern den nötigen Kontext und die erforderlichen Informationen bereitzustellen
• Als vergleichbare Projekte in der Branche mit ähnlichen Funktionen werden Confluence und Notion empfohlen

[GN⁺]

Hacker-News-Kommentare

• Ich schreibe über deutsche Bürokratie und stimme diesem Ansatz vollkommen zu.
  Die meisten meiner Guides beginnen mit „Was ist das, wer muss es tun und warum muss es getan werden?“. Wenn man nicht sicherstellt, dass die Leute aus den richtigen Gründen das Richtige tun, können sie sehr weit in die völlig falsche Richtung laufen.
  Die meisten Behörden-Websites erklären so etwas nicht, sondern verlangen nur das, was nötig ist, um den ihnen zugewiesenen Vorgang abzuschließen. Sie betrachten ihn nicht als Teil einer größeren Entscheidung und gehen davon aus, dass die Nutzer schon wissen, was sie tun.

  • Zum letzten Absatz: Die UK-gov-Website macht das sehr gut. Es gibt eine Landingpage, die den Vorgang erklärt, danach kommen Warnungen und Hinweise, und erst dann kann man das eigentliche Formular ausfüllen.
    Wenn man beim Google-Ergebnis zur Führerscheinverlängerung https://www.gov.uk/renew-driving-licence auf „Start Now“ klickt, sieht man, was ich meine.
    Aus Sicht eines „Power Users“ fühlt sich das manchmal wie ein Hindernis an, aber ich verstehe, dass man alle berücksichtigen muss.
  • Bei diesem Kommentar denke ich, dass dir Every Page Is Page One gefallen könnte. Der Kern ist: Menschen können auf jeder beliebigen Seite einer Dokumentationssite landen, deshalb sollte jede Seite schnell Kontext liefern und es den Nutzern leicht machen zu beurteilen, ob sie auf dem richtigen Weg sind.
    Daher kommt auch der Buchtitel. Jede Seite einer Site kann für einen Nutzer die erste Seite sein.
  • Ich wünschte, diesen Ansatz gäbe es in mehr technischer Dokumentation. Ich frage mich ständig, warum etwas auf eine bestimmte Weise gemacht wird, und schweife dann oft ab, was mich langsamer macht.

• Passt gut dazu, wie man LLMs nutzt. Ich bitte immer um Optionen und entscheide dann selbst, welche davon am meisten Sinn ergibt.
  Im Grunde verwende ich sie wie eine seltsame, magische Art von Dokumentation, die in jedem Moment einer Entscheidung unvollständige, aber nützliche mögliche Optionen ausspuckt.

  • Man kann dabei an einen Lehrling denken, der unter einem berühmten Künstler wie Leonardo arbeitet. Der Meister zeichnet die Konturen und Skizzen, und die Schüler füllen unter Aufsicht die leeren Stellen aus. Manchmal stiehlt der Meister auch Ideen der Schüler.
  • Könntest du ein Beispiel für diese Vorgehensweise geben?

• Wirklich gut. Kurz, auf den Punkt und einsichtsvoll. Ich denke eher in großen Zusammenhängen, deshalb ist mir nicht nur wichtig, wie man etwas macht, sondern auch warum und wie es in den größeren Kontext passt.
  Ich ermutige Entwickler, das Description-Feld von Jira-Storys und -Tasks aktiv zu nutzen und dort einen Überblick einzutragen, warum wir diese Arbeit machen und wie sie mit dem großen Ganzen zusammenhängt. Manche scheinen das nicht zu mögen, andere mögen es ziemlich gern.
  Mir gefällt, dass ich das große Bild des Projekts vermitteln kann, und die Entwickler sind zufrieden, weil sie durch dieses Verständnis unabhängiger arbeiten können.

• Zu messen, ob Dokumentation Menschen dabei hilft, gute Entscheidungen zu treffen, scheint deutlich schwieriger zu sein, als zu messen, ob sie ihnen hilft, Aufgaben erfolgreich abzuschließen.
  Der Grund, warum man auf aufgabenbasierte, prozedurale Dokumentation optimiert, ist, dass Unternehmen verlangen, den Wert des Dokumentationsteams nachzuweisen, es Nachfrage nach solcher Dokumentation gibt und es viele Möglichkeiten gibt, sie innerhalb kurzer Zeit zu messen und darüber zu berichten.
  Aber die Frage „Hat dieses Dokumentationspaket jemandem geholfen, das Richtige auf die richtige Weise zu bauen?“ ist schon für Organisationen in Bezug auf ihr eigenes Produkt schwer zu beantworten; abstrahiert man das auf die Wirkung von Dokumentation, wird es sehr unscharf.
  Das heißt nicht, dass man keine Dokumentation schreiben kann, die Entscheidungen unterstützt, sondern dass es sehr schwer ist, zahlenmäßig zu belegen, dass man das getan hat. Ich kann Dokumentationspakete danach einordnen, wie gut sie Nutzer unterstützen, die Entscheidungen treffen müssen, und die Begründung dafür erklären, aber ich weiß nicht recht, wie man das auf die Weise quantifiziert, die Unternehmen wollen.
  Ich frage mich auch, wie sich die Struktur eines Dokumentationspakets, das zur Unterstützung von Entscheidungen entworfen wurde, von einer Dokumentation unterscheidet, die Aufgaben unterstützt. Die großen Kategorien wären wohl weiterhin Konzepte, Referenz und Guides, aber es gäbe vermutlich deutlich mehr konzeptionelle Dokumente und mehr Raum, um Konzepte in Kontext zu setzen. Ich würde auch mehr Abhängigkeiten zwischen Themen und mehr Querverweise erwarten.

  • Interessant, dass dein erster Gedanke nicht „Wie kann ich das nutzen, um die Dokumentation zu verbessern, die ich schreibe?“ ist, sondern „Wie beweise ich, dass das die Dokumentation verbessert, die ich schreibe?“. Klingt, als würdest du in einem ziemlich engen Umfeld arbeiten.
  • An Orten, an denen man frei das tun kann, was man für die Nutzer für das Beste hält, etwa bei persönlichen Projekten, würde man Entscheidungsunterstützung wahrscheinlich zur Grundlage der Dokumentationsstrategie machen.
    Aus der Perspektive gewissenhafter Arbeit würde ich sagen: Wenn sich „Entscheidungsunterstützung“ für mein Projekt als das Beste anfühlt, habe ich die Pflicht, diese Strategie auch in meine berufliche Dokumentation mitzunehmen.
    Zum Glück sitzen mir keine kurzsichtigen Manager im Nacken, aber wenn ich am Arbeitsplatz überzeugen müsste, würde ich es so angehen: Zuerst die Logik der Strategie erklären. Entscheidungsunterstützung ist sinnvoll und überzeugend. Aufgabendokumentation wird weiterhin geschrieben, aber Aufgaben sind nur eine Teilmenge der Entscheidungsunterstützung.
    Danach würde ich ausführlich Beispiele aus Support-Tickets, Chatraum-Diskussionen usw. vorlegen, bei denen fehlende Entscheidungsunterstützung das Problem war. Aus intellektueller Redlichkeit würde ich sowohl die vollständige Liste dokumentationsbezogener Support-Tickets als auch die Teilmenge zeigen, die Entscheidungsunterstützung betrifft. Wenn der Anteil nicht vernachlässigbar ist, zum Beispiel 25 %, sollte man „Entscheidungsunterstützung“ genauer betrachten.
    Abschließend könnten Stakeholder Beispiele aus ihrer eigenen Arbeit nennen. Etwa: „Erinnert ihr euch, wie schwer es war zu entscheiden, auf welches CMS wir umsteigen?“

• Das ist das, was ich normalerweise einen heuristischen Ansatz nenne.
  Ich habe das Gefühl, dass Arbeit einen Ansatz wie Fuzzy Logic braucht. Allerdings funktioniert das am besten, wenn der Engineer bereits ein gewisses Maß an Erfahrung hat.
  Wenn jemand wenig Erfahrung hat, muss man deutlich stärker anleitend sein, selbst wenn die Person fähig und klug ist.

  • Thinking in Bets war eines der hilfreichsten Bücher für meine Herangehensweise an Software Engineering. Es ist kein Buch über Code, sondern darüber, wie man in Umgebungen mit begrenzten Informationen effektiv Entscheidungen trifft.
  • Ich bin mir nicht sicher, was es bedeutet, Arbeit mit einer Fuzzy-Logic-Herangehensweise anzugehen. Könntest du das etwas näher ausführen?

• Einen guten Ansatz, Entscheidungen im Teamkontext zu treffen, erklärt Rich Hickey hier: https://www.youtube.com/watch?v=c5QF2HjHLSE
  Der Vortrag heißt „Design in Practice“, handelt aber eigentlich von Entscheidungsfindung.

• „Arbeit ist einfach alles, was getan werden muss, um von einer Entscheidung zur nächsten zu gelangen.“ — Venkatesh Rao, Tempo

• Ich habe schon Ähnliches vertreten. Man sollte Tools nicht nur auf hoher Ebene beschreiben – besonders weil Menschen oft in den Marketingmodus verfallen –, sondern darüber sprechen, welches Problem das Tool lösen soll und welche Kompromisse dabei eingegangen wurden.
  Dann lässt sich ein Tool samt verfügbaren Optionen, Modi usw. viel leichter in einen Kontext einordnen, und man kann schnell beurteilen, ob es zu einem passt.

• Dieser Rat ist etwas verwirrend. Wessen Entscheidungen sind gemeint? Die des Tool-Erstellers oder die der Nutzer?
  Im Allgemeinen wirkt das wie eine übermäßige Vereinfachung. Hilfreicher ist es zunächst zu verstehen, welche Art von Dokumentation man schreibt: lernorientiert, zielorientiert, verständnisorientiert oder informationsorientiert [1].
  Wenn man zum Beispiel die API einer Funktion nachschlägt, kann es nerven, mit Informationen zu „Entscheidungen“ überhäuft zu werden.
  1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

  • Dokumentation sollte immer Nutzerbedürfnisse behandeln. Das verschwindet nicht. Das gilt auch für Diataxis, die vier Quadranten der erwähnten Dokumentation.
    Ich glaube, dieser Artikel findet Anklang, weil er einen blinden Fleck zweier bekannter Strategien sichtbar macht. Alle versuchen, nutzerzentrierte Dokumentation zu erstellen, und viele Teams folgen Diataxis, aber trotzdem haben sie Schwierigkeiten, mithilfe der Dokumentation Dinge zu erledigen.
    Wenn man von der Grundperspektive ausgeht, dass „Dokumentation Entscheidungen unterstützen sollte“, kann das ein Weg sein, Dokumentation nützlicher zu machen.

• Es ist wichtig zu wissen, wie Menschen mein System nutzen, um Entscheidungen zu treffen. Dieses Wissen halte ich für unverzichtbar, um ein System zu warten, zu erweitern oder neu zu bauen.
  Der Text schlägt jedoch eine höhere Verantwortung vor: den Entscheidungsprozess der Nutzer zu dokumentieren und Kontext, Optionen sowie die Folgen von Entscheidungen aufzuzeigen.
  Ich habe an einem „Decision-Support-System“ mit genau dieser Verantwortung gearbeitet, und es wurde sehr schnell komplex. Menschen diskutieren gern über Ergebnisse, selbst wenn deren Folgen zu 100 % sicher bekannt sind. Sie mögen auch keine automatischen E-Mails mit Unsicherheit, und sie mögen es nicht, wenn Dokumentation eine binäre Entscheidung verlangt, obwohl es in der Realität viel mehr Optionen gibt.
  Über diesen Artikel hinaus würde ich mir wünschen, dass das Buch das Konzept der Kontrolle behandelt. Damit Dokumentation ihre Autorität behält, braucht es für ein dokumentiertes Verhalten ein gewisses Maß an Garantie oder Durchsetzung. Meiner Meinung nach ist das Fehlen von Autorität und Kontrolle ein häufiger und großer blinder Fleck von Schreibinitiativen wie https://www.plainlanguage.gov.

  • Um noch einmal zu zitieren, was ich auf r/technicalwriting zu diesem Artikel geschrieben habe: Das wirklich Wichtige an Bakers Idee ist, dass die Lehre in der technischen Dokumentation absolut auf Aufgabenorientierung ausgerichtet ist.
    Wenn man professionelle technische Redakteure befragt, würden viele wohl sagen, dass „Nutzern dabei zu helfen, Aufgaben zu erledigen“ das Hauptziel von Dokumentation ist – vielleicht sogar DAS Hauptziel.
    Bakers kurzes Zitat ist in dem lateinischen Sinn von „zur Wurzel zurückkehren“ ziemlich radikal, weil es nahelegt, dass eine unserer Grundannahmen erheblich unzureichend ist.
    Für mich ist Bakers Idee interessant, weil sie einen deutlich höheren Maßstab setzt als den, der derzeit von technischer Dokumentation erwartet wird. Viele Dokumentationen gehen davon aus, dass „Mission erfüllt“ ist, sobald eine Aufgabe dokumentiert ist, aber Baker scheint zu sagen, dass das allein nicht reicht.
    Aufgaben müssen natürlich weiterhin dokumentiert werden, aber Aufgaben sind eine Teilmenge der Informationen, aus denen Entscheidungen bestehen.
    Ich erinnere mich nicht, ob Bakers Buch Kontrolle in dem hier gemeinten Sinn diskutiert hat. Für mich ist das eine neue Idee, danke dafür.
    Ein konkretes Beispiel für Kontrolle, das mir einfällt: Ein großer Teil meiner Dokumentation hängt von Seiten anderer Open-Source-Projekte ab. Wenn diese externen Seiten von geringer Qualität sind, sollte es möglicherweise auch in meiner Verantwortung liegen, diese Dokumentation zu verbessern. Viele würden Dokumentation außerhalb der eigenen Website nicht als eigene Verantwortung ansehen, aber wenn man wirklich Entscheidungen unterstützen will, spielt es keine Rolle, wer diese Dokumentation hostet.
    Vielleicht lässt sich viel daraus lernen, ein guter Open-Source-Bürger zu sein.