SELFHTML:Umstellung auf die neue Struktur

Aus SELFHTML-Wiki

[Bearbeiten] Motivation

Als das Wiki aufgesetzt wurde, wurden auch die meisten der jetzigen Namensräume konfiguriert, so auch der Namensraum Doku:, der für den Hauptteil der Dokumentation vorgesehen war. Leider erwies sich das als kontraproduktiv zur Arbeitsweise der verwendeten MediaWiki-Software. Die ist mehr für ein Lexikon mit Begriffen im Hauptnamensraum (das ist der ohne einen Vorsatz) ausgelegt und weniger gut für hierarchische Dokumentationen, wie diese hier.

Die Suchfunktion beispielsweise kann einen Artikel direkt anspringen, wenn das Suchwort mit dem Titel übereinstimmt. Das funktioniert aber nicht, wenn der Artikel sich nicht im Hauptnamensraum befindet.

Manche Stichwörter (zum Beispiel font) sind mehrdeutig und nicht nur einem Themenbereich zuzuordnen. Die Wikipedia löst dieses Problem, indem mehrere Artikel erstellt werden, die jeweils einen klärenden Zusatz in Klammern angehängt bekommen, wie font (html) und font (css).

Im Gegensatz zu einem Lexikon, in dem die Stichwörter mehr oder weniger zusammenhanglos aufgeführt werden, ist eine Dokumentation deutlich klarer strukturiert beziehungsweise strukturierbar. Hier kann man die Bereiche HTML und CSS erstellen und die jeweilgen font-Seiten darunter einsortieren, à la HTML/Elemente/font und CSS/Eigenschaften/font. Daraus geht auch klar hervor, in welchem Zusammenhang das jeweilige font steht.

Mit dieser Strukturierung ergibt sich aber auch wieder der Nachteil, dass die Suchfunktion nicht direkt eine dieser Unterseiten anspringen kann, wenn nur der Begriff statt des vollständigen Titels der Seite eingegeben wurde. Doch es ergibt sich ein entscheidender Vorteil. Für diese Seiten mit Unterseiten erstellt die Wiki-Software ohne weiteres Zutun einen Breadcrumb-Pfad. Das heißt, auf die Seiten zu HTML und HTML/Elemente respektive CSS und CSS/Eigenschaften wird gleich unter dem Seitentitel verwiesen und man muss nicht händisch eine Navigation einbauen, so wie das bei Stichwort-Seiten im Hauptnamensraum der Fall wäre.

[Bearbeiten] Lösung

Die beiden Vorteile lassen sich mit einem Kompromiss nutzen. Der eigentliche Text zu den Stichwörtern wird auf einer (Unter-)Seite in der jeweiligen zum Themengebiet spezifischen Struktur einsortiert (Beschreibungsseite). Für die Suchfunktion und zur besseren Verlinkbarkeit (…/begriff statt …/struktur_1/struktur_2/begriff) wird pro Begriff eine Seite direkt im Hauptnamensraum angelegt, die entweder eine direkte Weiterleitung auf den strukturierten Titel ist oder einen Begriffsklärungstext mit Auswahlmöglichkeit erhält (Stichwortseite).

[Bearbeiten] Beispiele

CSS-Eigenschaft font-size:

• font-size als Stichwortseite mit Weiterleitung auf die Beschreibungsseite CSS/Eigenschaften/Schriftformatierung/font-size

font als CSS-Eigenschaft, HTML-Element, Schriftart-Datei, …

• font (Begriffsklärung) als Begriffsklärungsseite mit Verweisen zu
  • CSS/Eigenschaften/Schriftformatierung/font
  • HTML/veraltet/font
  • Glossar:Font
  • und gegebenenfalls weitere.
• die CSS-Eigenschaft font wird wohl am häufigsten nachgefragt werden, deshalb
  • font als Weiterleitung auf CSS/Eigenschaften/Schriftformatierung/font

Weitere Hinweise zur Begriffsklärung unter Hilfe:Begriffsklärung.

[Bearbeiten] Gute und weniger gute Seitentitel

[Bearbeiten] Stichwort im Singular

Die bevorzugte Schreibweise für ein Stichwort im Seitentitel sollte dessen Singular (Einzahl) sein. Die Einhaltung dieser Empfehlung dient hauptsächlich der Konsistenz bei der Seitenbenennung. Wenn es angemessen erscheint, kann davon abgewichen werden.

[Bearbeiten] Dopplungen vermeiden

Durch die Strukturierung ergibt sich der Kontext, in dem ein allgemeines Wort zu sehen ist, oftmals bereits aus der Struktur selbst. Dass es sich bei Elemente um HTML-Elemente handelt, wird bereits deshalb klar, dass bei einem Seitentitel wie HTML/Elemente dieses Elemente eine Unterseite von HTML ist. Bei HTML/HTML-Elemente bringt der Teil „HTML-“ keine Vorteile mehr, er verlängert nur den Seitentitel.

Noch ein Beispiel: Referenz:CSS/Eigenschaftenreferenz – Der Namensraum Referenz zeigt bereits deutlich genug, dass die Seiten darin eine Referenz darstellen, so dass statt …/Eigenschaftenreferenz ein …/Eigenschaften ausreichend ist.

[Bearbeiten] Sonderzeichen vermeiden

Zur Bennennung von Seiten sollten wenn möglich nur Buchstaben, Ziffern, Leerzeichen und das Bindestrich-Minus verwendet werden. Andere Zeichen ergeben oftmals beim Verlinken schlecht lesbare URLs. Die korrekte Schreibweise kann im Artikeltext geklärt werden.

Beispielsweise werden Funktionsnamen mitunter mit einem anschließenden Klammernpaar geschrieben, das andeuten soll, dass es sich um eine Funktion handelt. Diese Klammern sind aber nur syntaktisch notwendiges „Beiwerk“ bei der Anwendung und gehören nicht direkt zum Namen der Funktion. Und besonders bei Stichwortseiten für mehrdeutige Bezeichner ist es eher von Nachteil, wenn sie in vielen syntaktischen Schreibweisen existieren, statt nur in einer mit dem „nackten“ Namen.

[Bearbeiten] Prägnante Titel wählen

Der Titel einer Seite sollte nicht zu ausschweifend gewählt werden. Dies macht sonst die Weitergabe von Links unhandlicher als notwendig. (Linkverkürzer sind auch keine Lösung.) Erläuternde Texte zu einem Begriff stehen einerseits sowieso im Fließtext der Seite, andererseits können auf verweisenden Seiten die Links mit einem alternativen Verweistext versehen werden oder Erläuterungen neben den Link geschrieben werden.

Statt JavaScript/…/window/name (Name des Fensters) soll die Seite nur JavaScript/…/window/name benannt werden und beim Verlinken kann man beispielsweise [[JavaScript/…/window/name|name (Name des Fensters)]] notieren.

[Bearbeiten] Einzelseiten statt Monsterseiten

Wenn eine Seite zu groß wird, werden unter anderem Bearbeitungen immer unhandlicher. Dieses Problem kann man teilweise umgehen, indem man nur einen Bereich zum Bearbeiten wählt und nicht die gesamte Seite.

Diese Bereiche ergeben sich automatisch anhand von Zwischenüberschriften. Für jede Überschrift setzt das verwendete Wiki-System automatisch einen Anker, der aus dem Text der Überschrift gebildet wird, so dass man diesen Teilbereich aus dem Inhaltsverzeichnis der Seite oder von anderswo aus verlinken kann (…/Seitenname#Überschrift).

Im Gegensatz zur Verlinkung auf eine Seite an sich, werden die Links auf Anker bei einer Änderung der Überschrift nicht weiter berücksichtigt. Beim Verschieben/Umbenennen einer Seite wird zumindest unter dem alten Namen eine Weiterleitung erstellt. Anker werden nur im Browser ausgewertet und beim Klicken auf Links nicht an den Server übermittelt, so dass dieser rein technisch nicht in der Lage ist, Weiterleitungsmaßnahmen zu ergreifen. Zur Unterstützung beim Pflegen von Links gibt es auch keine Funktion „Verweise auf Anker finden“. Genauer gesagt, sie tauchen auf keiner der Wartungslisten auf. Im Gegensatz dazu kann man Links auf eine bestimmte Seite problemlos anzeigen lassen und die Wartungslisten verwenden.

Das bedeutet vor allem für Themen, die regelmäßig auch direkt angesprungen werden, dass die Stabilität von Verweisen leidet. Solche Themen sind beispielsweise die Beschreibungen von Eigenschaften und Methoden der Javascript-Objekte oder von Attributen der HTML-Elemente. Nicht unbedingt darunter fallen zum Beispiel Abschnitte in einem Tutorial.

• JavaScript/…/window ist die Seite für allgmeine Informationen zum window-Objekt
• Die Seiten für Eigenschaften und Methoden werden benannt:
  • JavaScript/…/window/name
  • JavaScript/…/window/blur
  • usw.
• HTML/…/img ist die Seite für das HTML-Element img
• Die Seiten für dessen Attribute sind:
  • HTML/…/img/src
  • HTML/…/img/alt
  • usw.

Allerdings ist diese Vereinzelung teilweise auch nachteilig für den Leser. Wenn er sich zwischen den Abschnitten hin- und herbewegen möchte, muss er die Seiten wechseln. Die im Browser eingebaute Suchfunktion wirkt nur auf einzelne Seiten und nicht übergreifend. Beispielsweise bestehen reguläre Ausdrücke üblicherweise aus Sonderzeichenkombinationen, die sich schwer bis gar nicht über Suchmaschinen finden lassen. Die Browser-Suchfunktion kann sie jedoch innerhalb einer Seite finden, bei aufgeteilten Seiten hingegen nicht mehr.

Diese Nachteile kann man ohne das Hinzufügen der Nachteile für das Bearbeiten von großen Seiten umgehen, indem auf der übergeordneten Seite oder einer eigens angelegten Zusammenfassungsseite diese Einzelseiten wie eine Vorlage eingebunden werden. An deren Stelle erscheint für den Leser der gespeicherten Seite der Inhalt dieser Vorlage / Einzelseite, im Code bleibt weiterhin der Vorlagen-Verweis stehen.

Ansichten