User Documentation In diesem Tutorial kann man lernen, wie man ein Tutorial erstellt.
Ein Tutorial ist eine Lektion, die durch eine Reihe praktischer Schritte führt. Es bietet eine Lernerfahrung durch Tun. Es ist der beste Weg, sich mit einem Thema vertraut zu machen, das einem noch nicht bekannt ist. Tutorials sind in jeder Dokumentation von entscheidender Bedeutung: Sie führen Neulinge ein, begleiten die ersten Schritte, sind das Schaufenster und vermitteln einen angenehmen und einfachen Einstieg in ein Thema. Einer der „Tricks“, um dies zu erreichen, besteht darin, alles wegzulassen, was im Lernprozess ablenken könnte. Zum Beispiel:
- Alternative Wege, etwas zu tun, oder Wege, etwas sehr Spezifisches zu tun.
- Vollständige Referenzen aller Optionen und eine technische Beschreibung ihrer Struktur.
- Detaillierte Erklärungen und historische Hintergründe.
Diese zusätzlichen Informationen lassen sich am besten separat bereitstellen. Es sollte möglichst vermieden werden, sie mit einzubauen, da dies das Tutorial nur unklarer macht. Dies ist das Hauptprinzip des Diátaxis-Frameworks, einer systematischen Methode zur Verbesserung der Dokumentation. Die oben genannten zusätzlichen Informationen sollten in entsprechende Anleitungen, Referenzen und Erklärungen eingebaut werden. In den Anleitungen kann man schnell nachlesen, wie man etwas Bestimmtes erledigt. In Referenzen kann man nachschlagen, wie Dinge funktionieren, welche Optionen sie bieten und wo man weitere Informationen findet. Mit Erklärungen kann das Verständnis des Themas vertieft werden.
Obwohl ein Tutorial eine Einführung in ein Thema bietet, richtet es sich nicht ausschließlich an Anfänger. Es kann auch eine Einführung in ein fortgeschrittenes Thema sein! Zu Beginn des Tutorials sollte klar angegeben werden, welches Wissen oder welche Fähigkeiten benötigt werden, um das Tutorial durchzuführen.
Wenn man jemandem das Kochen beibrennt, müssen Dinge wie Schnitttechniken, die Benutzung eines Ofens und andere grundlegende Küchenkenntnisse erklärt werden. Man beginnt mit einem einfachen Rezept, vorzugsweise etwas, das leicht ein schönes Endergebnis liefert. Dieses Endergebnis selbst ist nicht das Hauptziel: Es sollen bestimmte Fähigkeiten vermittelt werden. Genau das tut ein Tutorial. Wer bereits kochen kann und etwas Bestimmtes zubereiten möchte, braucht kein solches Tutorial, sondern ein Rezept. Rezepte sind die Anleitungen des Kochens.
Schritt für Schritt
So wird ein Tutorial erstellt:
- Informationen zum Thema sammeln. Vorhandene Dokumentation, Videos usw. Dinge notieren, die verwirrend waren oder deren Verständnis Zeit gekostet hat. Gibt es Fragen zu diesem Thema im Forum?
- Welche Konzepte sind beteiligt? Eine kleine Skizze kann dabei helfen. Nicht versuchen, vollständig zu sein, sondern klarstellen, was für dieses Tutorial wichtig ist und was nicht.
- Ist spezielles Wissen oder eine bestimmte Fertigkeit nötig, die im Tutorial vermittelt werden muss?
- Ein Beispiel erstellen, in dem alle Konzepte und Fertigkeiten verwendet werden können, die im Tutorial vermittelt werden sollen. Das Beispiel so einfach wie möglich gestalten.
- Schritte definieren und aufschreiben, die zu einem Endergebnis führen. Jeder Schritt sollte vom Lernenden nachvollziehbar sein.
- Alle Erklärungen, Referenzen, Alternativen und Sonderfälle herausfiltern und in separaten Beiträgen unterbringen.
- Eine Einleitung schreiben. Was wird in diesem Tutorial gelernt? Alle notwendigen Voraussetzungen zur Durchführung des Tutorials erwähnen.
- Die Zusammenfassung schreiben. Was wurde gelernt? Es können auch nächste Schritte erwähnt werden, um mehr zu lernen.
- Screenshots mit Anmerkungen hinzufügen, um die durchzuführenden Aktionen zu veranschaulichen. Tipp: Zahlen im Screenshot verwenden und Erklärungen im Text geben. Das erleichtert die Wiederverwendung des Screenshots in Übersetzungen und minimiert den Aufwand für sprachspezifische Screenshots.
- Diagramme hinzufügen, um Strukturen, Beziehungen und Abläufe zu erklären.
- Die begleitenden Beiträge mit Erklärungen, Referenzen und Anleitungen hinzufügen.
- Alle Beiträge zu einem Thema unter einem Übersichtsbeitrag zusammenfassen, der erklärt, was was ist, wie sie zusammenhängen und wo man anfangen sollte.
Beispiel: Einen Beitrag in Joomla erstellen und veröffentlichen
Als Beispiel wird nun ein Tutorial erstellt, wie man einen Beitrag unter einem Menüeintrag in Joomla erstellt und veröffentlicht.
Informationssammlung
Im Benutzerhandbuch finden sich relevante Beiträge unter „Erste Schritte“, „Beiträge“ und „Menüs“. Zu Beginn mit Joomla ist es oft verwirrend, dass ein Beitrag nach dem Erstellen nicht sichtbar ist, obwohl er als „veröffentlicht“ markiert wurde. Damit der Beitrag sichtbar ist, muss ein Link dorthin bestehen. Es gibt mehrere Möglichkeiten, einen solchen Link zu erstellen (wie einen Menüeintrag, ein Kategorie-Blog-Layout oder das Platzieren auf dem Blog-Layout der Startseite durch Markieren des Beitrags als Haupteintrag oder eine Verlinkung von einem anderen Beitrag), aber der Fokus liegt nun darauf, den Beitrag über einen Menüeintrag verfügbar zu machen.
Konzepte & Fertigkeiten
Es gibt 'Inhalt', 'Beitrag', 'Menü' und 'Menüeintrag'. Diese Begriffe müssen geklärt werden. Es wird gezeigt, wo diese Dinge im Administrator-Menü zu finden sind. 'Kategorien' oder 'Haupteintrag' werden in diesem Tutorial ausgelassen.
Voraussetzungen
Zugriff auf die Administratorseite einer funktionierenden Joomla-Website und Kenntnis darüber, wie man sich anmeldet.
Ziel
Unser Ziel ist es zu lernen, wie man einen neuen Joomla-Beitrag und einen neuen Menüeintrag erstellt, unter dem wir unseren Beitrag platzieren.
Schritte
Mit den folgenden Schritten wird unser Ziel erreicht:
A. Einen Beitrag erstellen
- Im Joomla-Administrator-Panel anmelden.
- Zuerst wird der Beitrag erstellt. Im Menü "Inhalt" links navigieren und "Beiträge" auswählen.
- "Neu" anklicken, um einen neuen Beitrag zu erstellen.
- Titel und Inhalt für den Beitrag eingeben.
- "Speichern & Schließen" anklicken, um den Beitrag zu speichern.
B. Einen Menüeintrag erstellen, der auf den Beitrag verlinkt
Um den Beitrag auf der Website anzuzeigen, wird ein Menüeintrag erstellt, der auf den Beitrag verlinkt. Im Menü "Menüs" links navigieren und "Hauptmenü" auswählen.
- Genau wie bei einem Beitrag "Neu" anklicken, um einen neuen Menüeintrag zu erstellen.
- Einen Titel für den Menüeintrag eingeben. Dies ist der Titel, wie er im Menü erscheinen wird. Er muss nicht mit dem Titel des Beitrags übereinstimmen. Üblicherweise ist er kürzer als der Titel eines Beitrags, damit er besser ins Menü passt.
- Einen Menüeintrag-Typ auswählen: unter "Beiträge" "Einzelner Beitrag" auswählen.
- Den Beitrag auswählen: den gerade erstellten Beitrag auswählen.
- Zur Website gehen und aktualisieren. Herzlichen Glückwunsch: der Beitrag kann nun durch Anklicken des Menüeintrags angesehen werden.
Einleitung
Die Einleitung schreiben: was wird in diesem Tutorial gelernt und welche Voraussetzungen sind notwendig.
Zusätzliche Informationen herausfiltern
Kann irgendetwas von dem bisher Geschriebenen weggelassen werden? Nun, in Schritt 2 der Erstellung eines Menüeintrags wurde erwähnt, dass der Titel des Menüeintrags nicht mit dem Titel des Beitrags übereinstimmen muss. Ist das eine notwendige Ergänzung für dieses Tutorial? Falls nicht, sollte es vorerst weggelassen werden. Es gibt jedoch einen Hinweis auf einen spezialisierteren Artikel über Beitragstitel und Menütitel und wann sie angezeigt werden, einschließlich der allgemeinen Beitragsoptionen, der individuellen Beitragseinstellungen unter dem Optionen-Tab, der Menüeintrag-Einstellungen unter dem Optionen-Tab des Menüeintrags und mehr. Es wäre auch gut, einen referenzartigen Artikel darüber zu erstellen, wie Beiträge, Kategorien und Menüeinträge zusammenwirken; in einem solchen Artikel sollte versucht werden, vollständig zu sein und alle Möglichkeiten aufzulisten. Eine spezialisierte Anleitung könnte sein: "Wie wird der Beitragstitel angezeigt?", welche die Einstellungen in den allgemeinen Beitragseinstellungen sowie in den individuellen Beitrags- und Menüeintrag-Einstellungen zeigt. Eine Erklärung könnte etwas über den Hintergrund erzählen, warum Joomla "Beitrag" verwendet, wo zum Beispiel WordPress "Post" verwendet, oder wie der Beitrag auf der finalen Seite dargestellt wird.
Fazit
Alles in einer Zusammenfassung zusammenfassen. Und einige mögliche nächste Schritte erwähnen, um mehr zu lernen (wie: ein Tutorial über das Hinzufügen einer Kategorie oder eine Anleitung über die Speichern-im-Menü-Abkürzung).
Bilder und Grafiken
Screenshots erstellen, die die beteiligten Schaltflächen und Felder beim Erstellen eines Beitrags und eines Menüeintrags zeigen. Die beteiligten Schaltflächen und Felder markieren.
Zur Verdeutlichung könnte ein Diagramm hinzugefügt werden, das zeigt, wie ein Beitrag "unter" einem Menüeintrag platziert wird.
Referenzen, Anleitungen und Erklärungen hinzufügen
Alle zusätzlichen Informationen und Anweisungen in separate Artikel einfügen.
Überblick
Falls es mehrere Artikel zu einem Thema gibt, sollte ein Übersichtsartikel erstellt werden, der erklärt, wie die Artikel zusammenhängen und wo man beginnen sollte.
Übung
Mit der Erstellung des oben genannten Tutorials beginnen, wie man einen Beitrag in Joomla erstellt und veröffentlicht. Der beste Weg zu lernen ist, es selbst zu tun. Ein Beispiel, wie dies aussehen kann, wird im aktuellen Benutzerhandbuch auf dieser Seite veröffentlicht. Aber wir würden uns freuen, Ihre Version dort einzufügen, wenn Sie die aktuelle verbessern können.
(dieser Beitrag wurde auch im Joomla Community Magazine vom Februar 2025 veröffentlicht)