Tutorials nach einer App-Entwicklung richtig schreiben

Hast du als Servicepartner der tricoma AG eine App entwickelt, sollte mindestens ein Tutorial zur Einrichtung und/oder Handhabung geschrieben worden sein, bevor diese App veröffentlicht wird.

In diesem Tutorial geht es darum, worauf du beim Verfassen von Tutorials achten solltest. Ziel ist es, dass die neuen Tutorials einen einheitlichen Stil erhalten. Dem Leser soll es so einfach wie möglich gemacht werden, die Inhalte zu verstehen und umzusetzen.

Grundsätzliches

Bitte beachte die grundsätzlichen Punkte:

• Der Text ist in der Du-Form.
• Der Text sollte so viel wie nötig, aber so wenig wie möglich Inhalt haben. Beispielsweise ist die Erklärung des Kontextes zwar notwendig, aber dabei muss man nicht um den heißen Brei herumreden.
• Die Anleitung sollte einfach und klar auf den Punkt gebracht werden. Bei Bedarf können weitere Tutorials verlinkt werden.
• Verlinkungen zu anderen URLs sollten immer in neuen Tabs geöffnet werden.
• Keine Gendersprache, da diese kein richtiges Deutsch ist und das Lesen unnötig erschwert.
  Siehe dazu ein YouTube-Beitrag HIER.
• Nutze Screenshots, denn Bilder sagen mehr als 1000 Worte. Persönliche oder vertrauliche Informationen sind unkenntlich zu machen.
• Prüfe anschließend den Inhalt auf Grammatik- und Rechtschreibfehler sowie auf korrekte optische Darstellung.

Aufbau eines Tutorials

Öffne folgende Tutorials als Referenzbeispiel:
Einrichtungstutorial: App ManoMano Connector
Einrichtungstutorial: DHL Connector

Inhaltsverzeichnis

Auf der linken Seite sind in beiden Tutorials das Inhaltsverzeichnis mit Kapiteln sowie Unterkapiteln zu sehen. Wenn man draufklickt, springt man direkt zum Kapitel/Unterkapitel.

Die Kapitel bestehen bei Einrichtungstutorials entweder aus den oberen Reiter oder aus den Hauptmenüpunkten auf der linken Seite der App. Das hängt vom Aufbau der App ab:

Die Unterkapitel bestehen bei Einrichtungstutorials entweder aus den Unterpunkten der oben befindlichen Reiter oder aus den Untermenüpunkten in der Mitte der App. Das hängt ebenfalls vom Aufbau der App ab:

Wird ein Text als "Überschrift 2" formatiert, wird dieser automatisch zu einem Kapitel (h2-Tag im HTML-Code).
Wird ein Text als "Überschrift 3" formatiert, wird dieser automatisch zu einem Unterkapitel (h3-Tag im HTML-Code).

Es ist zwar möglich, den Text als "Überschrift 4" zu formatieren (h4-Tag), um einen Unterunterkapitel zu erstellen, aber aus optischen Gründen verzichten wir darauf.

Inhalt des Tutorials

Im Grunde hat jeder Autor seinen eigenen Stil, den er natürlich einbringen kann. Es gibt jedoch einige grundlegende Punkte, die berücksichtigt werden sollten, damit zumindest der Basisstil erhalten bleibt. Siehe dazu auch die beiden oben verlinkten Tutorials als Referenzbeispiele.

Screenshots

Je nach Umfang des Tutorials und der App ist es sinnvoll, pro Kapitel und/oder Unterkapitel einen Screenshot mit entsprechender Markierung einzufügen, damit der Leser sich orientieren kann und sicherstellt, dass er sich an der richtigen Stelle befindet.
Screenshots sollten ebenfalls verwendet werden, wenn ein Punkt, Thema oder eine Option genauer erläutert wird, um das Beschriebene zu veranschaulichen. Gerne können auch mehrere Screenshots genutzt werden, wie im Beispiel HIER.

Achte darauf, dass das gesamte App-Fenster im Screenshot sichtbar ist. Wichtig ist dabei, dass die Schriftgröße bzw. der Zoom korrekt eingestellt ist. Es ist nicht sinnvoll, zwar das gesamte App-Fenster im Screenshot zu haben, aber die Schrift dabei sehr klein ist und das Fenster so groß, dass viel weiße Fläche zu sehen ist.

Verwende am besten die kostenlose Software Greenshot, um Screenshots zu erstellen. Für Markierungen und Texte im Screenshot nutze die Farbe mit folgendem Hexadezimalcode: #5C9C0F

Um einen Screenshot einzufügen, lege ganz unten im Tutorial ein neues Bildelement an, indem du ein Bild hochlädst:

Jedes Text- bzw. Bildelement hat automatisch eine Prio auf der rechten Seite. Diese bestimmt die Reihenfolge der Elemente.

Bildelemente werden - wie in den Tutorials zu sehen ist - als kleines Fenster dargestellt. Das Bild vergrößert sich, wenn der Leser auf das Bildelement klickt. Mehrere Bildelement hintereinander werden im Tutorial von links nach rechts angezeigt.

Im Texteditor des Tutorials ist es ebenfalls möglich, ein Bild einzufügen, indem ein src-Attribut verwendet wird.. Aus optischen Gründen wird dies jedoch nicht empfohlen. Dieses Attribut wird eher verwendet, um z. B. kleine Icons im Text anzuzeigen, wie in diesem Beispiel HIER. Screenshots sollten jedoch - wie beschrieben - über ein Bildelement eingefügt werden.

Optionsbeschreibung bei Einrichtungstutorials

Wie in den Tutorials zu sehen ist, werden sämtliche Optionen der App erklärt.

Die Bezeichnung der Option ist in Standardgröße fett formatiert. Direkt darunter befindet sich die Beschreibung. Dabei ist - wie bereits erwähnt - so viel wie nötig, aber so wenig wie möglich Information gegeben. Achte auch darauf, den Kontext einer Option zu erklären, damit der Leser den Sinn der Option besser versteht. Auch kann ein weiteres, passendes Tutorial verlinkt werden.

+++++++++++

Beispiele

Option 1:
Mit dieser Option wird X aktiviert, um Y zu ermöglichen. Beachte dabei, dass Z eine Voraussetzung dazu ist, um X nutzen zu können.
Mehr Infos dazu findest du unter xxx

Option 2:
In diesem Dropdown-Menü kannst du X wählen. Dies ist wichtig, damit Y möglich ist.
Wie man Z einrichtet, findest du hier → xxx

+++++++++++

Negativbeispiel aus der Vergangenheit

b) Internes Passwort für die Abholung (erforderlich)
Hier geben Sie das interne Passwort für die Abhoung an.
Ein internes Passwort muss vergeben werden.

+++++++++++

In diesem fabelhaften Negativbeispiel ist es unübersehbar, wie es nicht gemacht werden sollte. Abgesehen vom Rechtschreibfehler weiß der Leser aufgrund dieser absolut mangelhaften Beschreibung überhaupt nicht:

• was das interne Passwort sein soll,
• welchen Sinn und Zweck dieses Passwort erfüllt,
• woher er dieses Passwort bekommt bzw. ob er ein beliebiges hier eintragen kann,
• warum es erforderlich ist und
• welche Auswirkung eine Passwortänderung mit sich bringt.

Du kannst gerne in den beiden Tutorials nachschauen, wie bisher die Optionen beschrieben wurden. Mit der Zeit hast du den Dreh raus.


Wenn du keinen Einrichtungstutorial schreibst, sondern eine anderer Art von Anleitung, wie z. B. eine Schritt-Für-Schritt-Anleitung oder die korrekte Nutzung eines Plugins, musst du natürlich nicht auf jede Option eingehen. In solchen Fällen ist es sehr individuell, wie du die Beschreibung angehst und gestaltest. Du kannst hier sehr kreativ sein. Wichtig ist nur, die oben genannten Grundsätze zu beachten.

Verlinkungen

Verlinkungen zu anderen Tutorials sind sehr einfach zu hinterlegen. Du brauchst nur die Tutorial-ID, die sich am Ende des externen Links befindet. Diese findest du bei jedem öffentlichen Tutorial auf tricoma.de, wenn du ganz nach unten scrollst oder in der Übersicht deiner Tutorials:

Im Texteditor hinterlegst du innerhalb einer eckigen Klammer die Tutorial-ID wie folgend:

[url=Tutorial-ID]


Bitte verlinke die Tutorials immer auf diese Weise, niemals über die URL in der Adressleiste! Denn egal, ob sich in der Zukunft der Pfad oder der Titel des Tutorials ändert, auf diese Weise bleibt das Tutorial immer mit einem Klick aufrufbar (außer es ist offline) und öffnet sich sogar in einem neuen Tab.

Möchtest du auf eine andere Webseite verlinken, die kein Tutorial von tricoma.de beinhaltet, dann markiere die entsprechende Textstelle und wandle sie in einen Hyperlink um. Die Funktion dazu ist im Texteditor vorhanden. Stelle den Hyperlink so ein, dass er sich in einem neuen Tab öffnet.

Einbetten von Videos

Du kannst Videos entweder – wie oben beschrieben – verlinken oder direkt ins Tutorial einbetten. Beim Einbetten ist das Video nicht nur direkt im Tutorial sichtbar, sondern kann auch ab einem bestimmten Zeitstempel abgespielt werden.

Öffne dazu das Video auf der Videoplattform und kopiere den Einbettungscode 1:1 in den Texteditor. Es ist am besten, den Code in einem eigenen Textelement einzufügen, um die Übersichtlichkeit bei der Bearbeitung des Tutorials zu wahren:

Auf diese Weise hast du auch die Möglichkeit, ein selbst gedrehtes Videotutorial in das Tutorial einzubetten, ohne viel schreiben zu müssen, wie im folgenden Tutorial als Beispiel:
Nutzung und Einrichtung von tricoma.AI (Videoanleitung)

Bei Bedarf weiterführende Tutorials verlinken

Wenn du dein Tutorial fertig geschrieben hast, ist es sinnvoll, am Ende weitere Tutorials zu verlinken, die zum Thema passen oder für den Leser interessant sein könnten. Sollte ein Tutorial bereits im Text verlinkt sein, muss es an dieser Stelle nicht erneut verlinkt werden. Je mehr nützliche Informationen der Leser erhalten kann, desto besser.

Tutorial online stellen

Ist dein Tutorial nun vollständig fertig? Dann muss es nur noch veröffentlicht werden. Aktiviere in der Übersicht beim entsprechenden Tutorial die Checkbox und klicke auf Aktualisieren:

Beim nächsten Online-Abgleich (Cronjob) wird das Tutorial veröffentlich bzw. Änderungen zu sehen sein.

Solltest du Fragen zu diesem Thema haben, steht dir unser Partnermanagement gerne zur Verfügung.