Verständlichkeit

Einer der wichtigsten Aspekte beim Schreiben von Tutorials, wenn nicht sogar der wichtigste überhaupt, ist die Verständlichkeit. Ein unverständliches Tutorial ist nutzlos. Verständlichkeit definiert sich hierbei natürlich auch wieder über die Zielgruppe. Wenn das Tutorial zwar für Profis verständlich ist, jedoch Anfängerthemen behandelt, ist das Tutorial letztendlich unverständlich, denn Profis gehören wohl nicht zur Zielgruppe.

Überblick schaffen

Insbesondere bei Projekt-Tutorials ist es deshalb z.B. hilfreich, zuerst einmal einen groben Überblick zu geben. Das muss keine Sammlung von UML-Diagrammen sein, die der Leser womöglich eh nicht versteht, jedoch sollte man den Leser nie darüber im Unklaren lassen, was letztendlich der dahinter liegende Gedanke, das Konzept, ist. Der sprichwörtliche rote Faden muss eindeutig erkennbar sein. Bei einem Projekt-Tutorial trifft dies in doppelter Weise zu: Einmal für das Tutorial selbst und dann natürlich auch für das resultierende Ergebnis, also das „Projekt“. Nur so, kann der Leser problemlos folgen.

Ebenso kann es bei Grundlagen-Tutorials nicht schaden, anfangs einen Überblick über das Thema zu geben und die zentralen Punkte schon mal zu nennen. Ähnliches gilt auch bei HowTos, wobei sich hier der Überblick auf eins, zwei Sätze beschränken sollte.

Wiederholungen, Definitionen und Beispiele

Bei diesen grundlegenden Gedanken, gilt – ähnlich wie bei mündlichen Vorträgen: „Sag, was du sagen willst, sag es und sag, was du gesagt hast“. Nur, was wiederholt wird, bleibt auch langfristig im Gedächtnis. Besonders bei langen Tutorials, die oftmals in Etappen gelesen werden, ist es sehr wichtig die wichtigen Grundkonzepte ständig zu wiederholen. Dass der Leser „zurückblättern“ muss um etwas nochmals nach zu schlagen, ist eine eher zu vermeidende Situation. Der Leser gerät dadurch aus dem Lesefluss.

Aber nicht nur grundlegende Gedanken müssen erläutert werden. Auch Begrifflichkeiten sollten unbedingt geklärt werden. Der Leser soll nicht noch Lexika wälzen müssen um das Tutorial zu verstehen. Auch hier ist natürlich wieder die Zielgruppe wichtig. Zu viele Erklärungen langweilen den Leser, zu wenige frustrieren ihn.

Man kann Begrifflichkeiten in einem separaten Abschnitt – vorzugsweise weit vorne – erklären und so eine grundlegende Basis schaffen, Glossare am Ende sind wohl eher etwas für sehr lange Werke und dann besteht natürlich noch die Möglichkeit Begriffe bei der ersten Verwendung zu erklären. Keine dieser Herangehensweisen ist falsch, jedoch gilt auch hier, was für die Grundgedanken gilt: Nur, wenn sie wiederholt und wiederholt erklärt werden, merkt sich der Leser die Begriffe. Dabei sollte man natürlich vermeiden den Leser zu langweilen, weswegen es geschickt ist, Begriffsdefinitionen implizit zu wiederholen. Beispielsweise könnte in einem Satz der Fachbegriff verwendet werden und im darauf folgenden könnte man statt diesen zu wiederholen einfach die „Übersetzung“ des Begriffs verwenden. Somit wird die Begriffsdefinitionen wiederholt, ohne dass es der Leser explizit als solche wahrnimmt. Beispiel:

„Ein Stack (auch Stapelspeicher oder Keller genannt) ist eine Datenstruktur, die nach dem LiFo-Prinzip (engl. last in first out) arbeitet. Das, was man als letztes auf den Stapel gelegt hat, wird später als erstes wieder herunter genommen.“

Das war die Definition. Im Folgenden können die Begriffe Stack, Stapel, Keller und LiFo-Speicher abwechselnd verwendet werden. So wiederholt der Leser implizit die Begriffe, erkennt sie als Synonyme und merkt sich ihre Bedeutung. Würde im Folgenden nur von Stack gesprochen, hätte der Leser recht schnell vergessen, dass man auch Stapel oder Keller sagen kann und legt er das Tutorial mal beiseite und liest später weiter, hätte er womöglich auch vergessen, dass ein Stack nach dem LiFo-Prinzip arbeitet. Zudem ist es sprachlich geschickter Wortwiederholungen durch Synonyme zu umgehen.

Somit sind wir auch schon beim nächsten Punkt: bei den Beispielen. Beispiele sind fürs Verständnis essentiell wichtig. Oftmals wird der Fehler begangen nur eine formale Definition zu geben, jedoch keine Beispiele zu geben, die dem Leser veranschaulichen, ob er die Definition richtig verstanden hat. Zudem prägen sich Beispiele besser ein als trockene Definitionen. Man kann dies weiter unterstützen, indem man Beispiele interessant und lustig gestaltet und nicht ständig immer nur von „Foo“ und „Bar“ spricht. Dabei sollten die Beispiele immer noch einigermaßen natürlich sein. Macht man sie zu lustig und zu gekünstelt, so kann es passieren, dass der Leser sie nicht mehr ernst nimmt, d.h. nicht glaubt, dass das, was für das künstliche Beispiel gilt, auch für andere Situationen – eben solche in der Praxis – zutrifft.

Beispiele sind also sehr wichtig, jedoch ist es ebenso falsch sich ausschließlich auf Beispiele zu stützen. Allgemeine Definitionen und Erklärungen müssen ebenfalls sein, sonst muss diese der Leser erraten, was u.U. auch zu falschen Interpretationen führen kann. Zu einem guten Tutorial gehört immer beides: knallharte Definition und anschauliches Beispiel.

Hintergrundwissen, Aufgaben und Detailgrad

Neben Faktenwissen und Beispielen ist es auch wichtig, dem Leser etwas an Hintergrundwissen mitzugeben. Bei Grundlagen-Tutorials ist dieses Hintergrundwissen ja gerade der eigentliche Inhalt, aber auch bei HowTos sind kurze Erklärungen wichtig, damit der Leser bei etwaigen Problemen oder kleinen Änderungen der Situation – beispielsweise neue Programmversionen – schnell selbst eine Lösung erarbeiten kann. Entsprechendes gilt natürlich auch bei Projekt-Tutorials.

Bei eben solchen kommt allerdings noch hinzu, dass es hier sinnvoll ist, dem Leser Aufgaben zu stellen, die er lösen soll. Seine Ergebnisse kann er dann leicht mit dem vergleichen, was im Tutorial vorgestellt wird. Wie schon erläutert bieten sich solche Aufgaben an, den Leser wirklich einmal anzusprechen und so den Lesefluss zu unterbrechen, damit der Leser die Aufgabe bearbeiten kann. Beispiel:

Auch bei Grundlagen-Tutorials sind Aufgaben und Verständnisfragen angebracht. Es bietet sich an, solche am Ende eines Kapitels zu stellen. Lösungen sollten natürlich auch verfügbar sein. Wichtig ist hierbei aber natürlich, dass der Leser die Lösung nicht sofort schon sieht. Also hier sollte gerade der Lesefluss unterbrochen werden — etwa indem die Lösung erst durch Anklicken eines Links erscheint. Bei Tutorials in PDFs oder auf Papier ist eine separate Seite mit Lösungen im Anhang sinnvoll. Das auf den Kopf Stellen der Lösung, was man ja öfters in Zeitschriften sieht, ist bei Tutorials meist nicht die beste Lösung, weil diese ja meist am Rechner gelesen werden.

Zu den angesprochenen Hintergrundinfos gehört auch, dass alles, was verwendet wird und nicht als Grundwissen vorausgesetzt werden kann, erklärt werden muss. Dazu gehören insbesondere auch Methodenparameter und ähnlicher Kleinkram. Ansonsten muss der Leser nachschlagen, was den Lesefluss wieder unterbricht. Andere Leser werden einfach weiter lesen, haben dann aber womöglich einen Teil des Tutorials nicht richtig verstanden. Man darf natürlich auch nicht vom Hölzchen aufs Stöckchen kommen, aber das, was gezeigt wird, sollte der Leser schon verstehen können.

Aber auch das Thema selbst hat einen Einfluss darauf, was erklärt werden muss. So sollte das Tutorial wirklich alles Wichtige zum Thema abdecken. Das gilt hauptsächlich, aber nicht ausschließlich, für Grundlagen-Tutorials. Der Leser soll sich umfassend informiert fühlen. Passen bestimmte Informationen des Themas nicht ins Tutorial, so ist das ein Hinweis darauf, dass der Titel vielleicht unpassend ist. Dieser sollte nicht mehr und nicht weniger versprechen, als auch wirklich gehalten wird.

Wir haben ja schon festgestellt, dass man den Leser normalerweise nicht aus dem Lesefluss reißen soll. Dazu gehört auch, dass man Vorwärts-Referenzen vermeidet. Das heißt so etwas wie „Das wird später noch erklärt“ sollte vermieden werden. Stattdessen ist es besser den Sachverhalt direkt an Ort und Stelle zu erklären. Darauf kann später immer noch genauer eingegangen werden. Das hat auch noch den Vorteil, dass wieder etwas Wichtiges wiederholt wird. So kann sich das der Leser besser behalten.

Wenn der Leser aber auf später vertröstet wird, nützt ihm das momentan auch nichts und er wird unweigerlich zuerst einmal etwas nicht verstehen. Das ist unbefriedigend und fördert nicht gerade das Verständnis. Manchmal ist es recht schwer, ohne Vorwärts-Referenzen aus zu kommen, aber man sollte sie dennoch vermeiden, wo es geht.

Verständliche Sätze

Nicht nur Aufbau und Inhalt sollen die Verständlichkeit fördern, auch die Sprache, die einzelnen Sätze sollen verständlich sein. So sollten komplizierte Schachtelsätze, sowie Einschübe in Klammern und Gedankenstrichen eher vermieden werden. Auch Negationen können problematisch sein. Statt „Das ist nicht gut.“, sollte man also besser „Das ist schlechter Stil.“ schreiben. Das Wörtchen „nicht“ wird einfach relativ schnell überlesen, was den Leser leicht verwirren kann. Noch schlimmer sind doppelte Verneinungen. Wenn sich die positive Formulierung zu künstlich anhört, kann man zumindest die Negationen vor Fehlinterpretationen etwas „schützen“, indem man ein „aber“ dazu packt. So muss der Leser schon zwei Worte überlesen um den Satz falsch zu verstehen. Beispiel: „Das ist aber typographisch gesehen nicht so gut.“

Grafiken und Code

Text ist nicht das Einzige, was gute Tutorials enthalten. Oftmals sind noch Grafiken, Bilder, Screenshots und natürlich Code enthalten. Dabei muss man sich jeweils fragen, was Sinn und Zweck dessen ist. Letztendlich unterbricht das nämlich wieder den Lesefluss. Der Leser springt vom Text in die Grafik und wieder zurück. Deshalb sollten Grafiken nur dort eingesetzt werden, wo sie die Verständlichkeit erhöhen. Oftmals sind sie aber in solchen Fällen dann überaus hilfreich.

Bei Grafiken ist es wichtig, diese im Text zu erläutern und auch aktiv darauf Bezug zu nehmen. Der Leser soll nicht noch lange raten müssen, was genau gemeint ist und für was die Grafik überhaupt da ist. Ein Satz wie „Grafik 4.2 zeigt das Innere eines Regenwurms, wobei der Kopf auf der linken Seite abgebildet ist.“ macht die Grafik verständlicher und bietet eine definierte Stelle, an der der Leser sich die Grafik ansehen soll. Am besten sind solche Hinweise am Ende eines Abschnitts aufgehoben, weil dann das wiederfinden der Textstelle einfacher ist.

Auch Code sollte man nicht im Übermaß liefern. Nur so viel, wie zum Verständnis notwendig ist. Den vollständigen Code kann man ja beispielsweise zum Download anbieten. Der Detailgrad des Codes hängt dann auch wieder von Thema und Zielgruppe ab. Bei Anfängertutorials ist ein hoher Detailgrad und ausführliche Kommentierung wichtig. Auch sollte hier der Code unbedingt kompilierbar sein.

Ist das Thema abstrakter und die Zielgruppe fortgeschrittener, kann auch der Code abstrakter und grobschrittiger sein. Oftmals bietet sich auch Pseudocode an, da sich dieser besonders leicht im Detailgrad variieren lässt. So kann man wirklich nur das Notwendige zeigen und den programmiersprachlichen Ballast beiseite lassen. Man sollte sich immer fragen, was man konkret zeigen will.

Bei besonders langen Projekt-Tutorials kann es auch geschickt sein, in regelmäßigen Abschnitten „Code-Checkpoints“ einzuführen, d.h. dem Leser nicht nur den vollständigen Quellcode zum Download anzubieten, sondern auch in mehreren Zwischenstadien. So kann der Leser das, was er selbst programmiert hat, mit dem Code-Checkpoint, also quasi der „Musterlösung“, vergleichen. Zudem verhindert das, dass der Leser nicht mehr folgen kann, weil er etwas nicht ganz hinbekommen oder anderes gelöst hat. Wichtig ist hierbei dann natürlich wie im gesamten Tutorial, dass der Quellcode auch wirklich mustergültig ist.

Hervorhebungen

Manchmal möchte man besonders wichtige Stellen hervorheben. In einigen Tutorials wird das gemacht, indem einzelne Begriffe fett gedruckt werden. Das ist aber typographisch gesehen nicht so gut. Besser sind hier separat hervorgehobene Abschnitte am besten noch mit einem Symbol gekennzeichnet, wie hier im diesem Tutorial gezeigt. Das erleichtert die Wiederauffindbarkeit von wichtigen Infos.

Auch um Zusatzinformationen, Regeln, Tipps, Aufgaben und Lösungen hervorzuheben sind solche hervorgehobenen Abschnitte sinnvoll. Mit Fußnoten sollte man hingegen vorsichtig sein. Diese können, wieder den Lesefluss unterbrechen. Deshalb eignen sie sich mehr für Informationen, die fürs Lesen erstmal unwichtig sind, beispielsweise Links zu weiterführenden Informationen.

Vorbildfunktion

Wenn man ein Tutorial schreibt, so sollte man sich immer im Klaren darüber sein, dass einem der Leser meist einfach glauben wird. Und zwar mehr, als einem vielleicht lieb ist. Man wird für den Leser implizit zu einer Art „Autorität“. Man tut ja so, als wüsste man, wovon man schreibt. Deshalb ist es auch wichtig, dass man es auch wirklich weiß.

Im Allgemeinen ist es so, dass der Autor eines Tutorials am meisten dabei lernt. Er muss nämlich jede Formulierung genau überdenken, ob sie auch genau so richtig ist und demnach genau über das recherchieren, was er schreibt. Alles muss er selbst durchdenken. Ein Leser kann sich damit zufrieden geben, wenn er nur 95% versteht. Ein Autor nicht. Der Leser wird einem glauben und im Zweifel das Tutorial wörtlich nehmen, ja mehr noch: Der Leser liest auch zwischen den Zeilen. Deshalb sollte man mit Übertreibungen, Späßen und Ähnlichem – so schön das auch ist und so schön es auch den Text auflockert – sehr vorsichtig sein. Der Leser könnte da etwas herauslesen, was gar nicht so gemeint ist.

Nun ist ein Tutorial keine wissenschaftliche Arbeit, von daher sind Bibliographien, etc. nicht nötig, jedoch sollte alles, was man schreibt, Hand und Fuß haben. „Das stimmt so irgendwie oder so ungefähr“ reicht hier nicht.

Auch hier ist es natürlich mal wieder wichtig, die Zielgruppe zu bedenken. Alle Beispiele, Definitionen und Aussagen müssen für die Zielgruppe mustergültig sein. In einem Anfängertutorial den Leser mit einem vollständigen objektorientierten Entwurf zu konfrontieren, ist wohl eher nicht sinnvoll. Hier muss der einigermaßen saubere Anfängeransatz als mustergültig angesehen werden. So bringt es nichts, abstrakte Klassen zu definieren, wenn man dem Leser gerade einmal beigebracht hat, was Funktionen sind.

Trotzdem sollte man keine groben Fahrlässigkeiten unkommentiert vorzeigen. So kann man z.B. nicht auf notwendige Ressourcenschutzblöcke verzichten, nur, weil man noch nicht erklärt hat, dass man Ressourcen auch wieder freigeben muss. Hier also besser vorbildlichen Code liefern und in eins, zwei Sätzen erläutern, was man da tut.

Ebenso ist es unumgänglich notwendig, dass Begriffe richtig verwendet werden. Wenn man Vereinfachungen annimmt, sollte man explizit darauf hinweisen, sonst wird das der Leser nicht erkennen. „Ich dachte das gilt ganz allgemein so. Im Tutorial wirds ja so gemacht.“ Zudem prägen sich falsche Begriffe recht schnell ein und Murphys Gesetz zufolge richtige fast überhaupt nicht. Besser also den Leser gleich an die richtigen Begriffe gewöhnen.

Kapitel: | Zurück | 1 | 2 | 3 | 4 | 5 | 6 | 7 | Weiter |