Hilfe:Wiki/Artikel

20min

Anfänger

Vielen Dank für dein Interesse an einer Mitarbeit bei SELFHTML. Manche Artikel wie unsere Referenzen können inhaltlich bearbeitet werden, sind aber in ihrer Struktur festgelegt. Tutorials führen in Form von Schritt-für-Schritt-Anleitungen in ein Thema oder einen Teilbereich ein.

Dieser Artikel zeigt, was man bei der inhaltlichen Gliederung und sprachlichen Gestaltung eines Tutorials beachten sollte.

Wie sehen gute Tutorials aus?

Gute Tutorials …

… erstellt man nicht von heute auf morgen. Anders als Blog-Beiträge, die nach hinten rutschen und dann langsam vergessen werden, bleiben Wiki-Tutorials (hoffentlich) immer auf dem neuesten Stand, wenn Nutzer im Wiki aktiv mitmachen und diese ständig verbessern.

… sind Selbstlerneinheiten, bei denen Nutzer den Artikel und die darin enthaltenen Beispiele nach dem SELF-Motto „Energie des Verstehens“ eigenständig durcharbeiten können.

Dennoch sollten bei der Neuanlage von Tutorials einige Grundsätze berücksichtigt werden. Du solltest neue Inhalte zunächst im eigenen Benutzernamensraum erstellen. Also etwa Benutzer:Dein Benutzername/neue Seite. Erst wenn der Artikel zum großen Teil fertiggestellt und im Forum vorgestellt und durch „Peer Review“ abgesegnet wurde, sollte er an die „richtige“ Stelle in der Dokumentation verschoben werden.

Empfehlung: Wenn ein Tutorial nun gar nicht mehr aktualisiert und überarbeitet werden kann, wird es nicht gelöscht, sondern depubliziert: d. h. durch eine Weiterleitung auf die entsprechende Portalseite ersetzt. So kann die Versionsgeschichte weiterhin eingesehen werden.
--Matthias Scharwies (Diskussion) 07:18, 25. Apr. 2023 (CEST)

Vorüberlegungen

Wie beim Erstellen von Unterricht und Prüfungen gilt auch hier, dass eine gründliche Vorbereitung spätere Nachfragen reduziert.

Formuliere für dich …

• 1–2 Lernziele
• die Zielgruppe und …
• das benötigte Vorwissen
• das Ziel als fertiges Beispiel

Einleitung

Tutorials sollten mit einer kleinen Einleitung beginnen, die den hervorgehobenen Haupttitel (in der Wikipedia Lemma genannt) der Seite enthält. An dieser Stelle braucht keine Überschrift gesetzt zu werden, der Seitentitel wird zur Hauptüberschrift.

Du steckst in einem kurzen einleitenden Abschnitt zuerst das Thema – eventuell auch abgrenzend von anderen Dingen – und die Zielgruppe ab, die der Artikel erreichen soll. Eine Erklärung, warum ein Thema relevant ist, erweitert die oben formulierten Lernziele.

Beachte: Lesedauer, Anspruch und benötigtes Vorwissen sollten schon in der Vorlage:Text-Info angegeben werden. Trotzdem kann so etwas in der Einleitung genauer ausgeführt werden.

Inhalt

Leser befinden sich zumeist in einer anderen Wissens-Umgebung als der Autor im Moment des Schreibens. Als Schreibender ist man „voll im Stoff“ und neigt schnell dazu, das eigene Wissen beim Leser vorauszusetzen. Also bitte nicht mit der Tür ins Haus fallen.

Aber nicht jedes Tutorial muss den head eines HTML-Dokuments oder die Einbindung von JavaScript erklären, sondern reduziert den Inhalt auf die festgelegten Lernziele (Didaktische Reduktion). Verweise im Fließtext oder der Vorlage:Text-Info auf bereits bestehende Tutorials, bzw. Referenz-Seiten und gehe gleich in medias res. Konsultiere auch die Glossar-Liste und verlinke das erste Aufkommen eines Begriffs mit bestehenden Glossareinträgen.

Genauso wichtig ist es ein gutes Ende – etwa in Form eines Beispiels zu finden und Sonderfälle lieber in einem Ausblick zu erwähnen oder auf weitere Tutorials zu verweisen.

Best Practices

Gute Tutorials zeigen nicht ein direkt einsetzbaren Code-Schnipsel, sondern erklären die verwendeten Komponenten und den Weg zum fertigen Beispiel.

Dabei sollten selbstverständlich die Grundsätze des Webdesigns eingehalten werden:

• semantisch korrekte Verwendung der HTML-Elemente
• Beachtung von Konventionen, die sich als allgemeingültig und empfehlenswert herausgestellt haben.
• Zugänglichkeit für alle Benutzer
• Responsivität auf allen Bildschirmen
• HTML/Tutorials/Trennung von Inhalt, Präsentation und Verhalten (Separation of Concerns)

Häufig werden Tutorials kürzer und verständlicher, wenn du dir anfangs Gedanken über die Barrierefreiheit machst und dann gleich passende Elemente verwendest, anstatt die Funktionalität erst nachträglich mit weiterem Code hinzuzufügen.

Strukturierung

Eine gute Strukturierung erzielt man, indem man die Inhalte in Abschnitte mit aussagekräftigen Überschriften gliedert.

Du kannst durchaus Überschriften mehrerer Ordnungen verwenden. Achte aber auf eine logische Folge. 20 Hauptüberschriften wirken weniger geordnet als wenige Hauptüberschriften mit jeweils mehreren Unterüberschriften. Diese Überschriften bilden dann die verschachtelte Liste des Inhaltsverzeichnisses, das dem Leser einen ersten Überblick verschafft.

Links und Quellenangaben

Fremde Ideen müssen durch Quellenangaben kenntlich gemacht werden und. Dabei sollte aber auf das Setzen von externen Links im Fließtext verzichtet und stattdessen Quellen mit Fußnoten angegeben werden.

Fußnoten werden mit

<ref>Quellenangabe</ref>

im Fließtext notiert und erscheinen dann unter Weblinks, falls der entsprechende Mediawiki-interne Tag gesetzt ist:

== Weblinks ==
<references/>

Empfehlenswert ist es, neben dem Link an sich eine kurze Erläuterung mitzuliefern:

Besim Karadeniz: Verstehen Sie mal das Internet!
Eine hervorragend gemachte Seite mit allgemeinverständlichen Erläuterungen zum Internet, TCP/IP, Adressierung und Tools. Nicht nur für Anfänger. Vielen Dank an Besim Karadeniz!

Autorenschaft

Anders als im Blog wird der Autor bei Wiki-Beiträgen nicht gekennzeichnet (nur in der Versionsgeschichte), da ermutigt werden soll, bestehende Artikel zu berichtigen, zu erweitern und nach einigen Jahren auch zu modernisieren.

Die Vorlage:Autorbox wurde nur für die Übertragung der Selfhtml-aktuell-Artikel, für die ein anderes Lizenzmodell gilt, geschaffen und sollte nicht mehr verwendet werden.

Sprache und Terminologie

In einem Wiki mit einer Vielzahl an Autoren bleibt es nicht aus, dass unterschiedliche Sprachstile entstehen. Jedoch sollte jeder Autor versuchen, sich am Stil von SELFHTML zu orientieren. Nicht, weil SELFHTML etwa der Stein der Weisen im Sprachstil sein will. Nein, einfach weil es dem Leser leichter fällt, einen einheitlichen Stil zu lesen.

Die Terminologie sollte daher möglichst einheitlich sein. Wenn z. B. hier von HTTP-Server und da von Webserver die Rede ist, sollte dies vereinheitlicht werden. Das gilt auch für uneinheitliche Schreibweisen wie Web-Server und Webserver. Zur Orientierung hilft auch ein Blick ins Glossar.

Das Motto „Die Energie des Verstehens“ sollte in allen Seiten des SELFHTML-Raums spürbar sein. Verständlichkeit und Transparenz sind höchstes Gebot. Kurze Sätze sind tendenziell besser als lange Sätze. Allerdings ist auch kein Telegrammstil und schon gar nicht das in vielen Online-Kommunikationen übliche Halbsatzgestammel erwünscht. Generell kann man jeden Text auf seine Qualität hin überprüfen, indem man für jeden darin enthaltenen Satz versucht, explizit zu begründen, warum der Satz da steht.

Komplexe Sachverhalte verlangen allerdings manchmal auch, sich dem Ziel des Verständlichmachens in mehreren Ansätzen zu nähern. Denn die angestrebten Aha-Effekte stellen sich nicht bei jedem Leser an der gleichen Stelle ein. In entsprechenden Textpassagen sollten sich zwei, drei oder mehrere Sätze bewusst ergänzen, indem sie den Sachverhalt aus verschiedenen Perspektiven erklären, z. B. einmal durch eine nüchterne Definition, dann durch einen Vergleich, dann durch eine Einordnung in Umgebungswissen, garniert durch Links dorthin.

An geeigneten Stellen – z. B. bei zusätzlichen Kommentaren oder in Beispielen – sind darüber hinaus durchaus Ironie und Esprit erlaubt und sogar erwünscht. Denn solche Bonbons für wache Geister lockern den Gesamttext auf und sorgen für einen intellektuellen Mehrwert, für den SELFHTML ebenfalls bekannt ist.

Hinweis:

Bei der Korrektur vorhandener Texte sollte nachsichtig vorgegangen werden. Insbesondere bei Zweifelsfällen sollte die Meinung des Autors ausschlaggebend sein.

Du oder Sie?

Ursprünglich hatte die Doku Leser konsistent gesiezt. Mittlerweile ist es genauso normal das „Du“ zu verwenden. Es sollte innerhalb eines Artikels jedoch konsistent gehandhabt werden.

• Mitmachen
• Hilfe
  (Übersicht)
• Seiten mit Mediawiki-Syntax formatieren