Weblog

Das neue Dokumentationskonzept

Die Dokumentation von YAML wurde vollständig neu gestaltet. Sowohl 2005 (YAML 1) als auch 2007 (YAML 3) erschien es gerechtfertigt, neben dem “wie” der Anwendung auch das “warum” der technischen Realisierung) ausführlich zu erläutern. Es gab in diesen Jahren kaum vollständige Dokumentationen zum Umgang mit Browserbugs und die Grundkonzepte von CSS2 waren für viele Entwickler noch vergleichsweise frisch. Diese Zeiten sind vorbei. Grobe CSS-Bugs, die massiv das Rendering einer Webseite beeinflussen, sind in den aktuellen Browsern mehr oder weniger ausgestorben, die Macken der alten Browsergeneration sind in zahlreichen Büchern und online umfassend dokumentiert. Zudem war die YAML-Doku in ihrer PDF-Fassung auf satte 150 Seiten angewachsen, die Pflege und Fortschreibung in zwei Sprachen war nicht mehr zu leisten.

Das neue Dokumentationskonzept behandelt zukünftig nur noch die Anwendung der einzelnen Features – also das “wie”. Lohn dieses neuen Konzepts: die Doku liegt nun als offline-taugliche HTML-Datei dem Zip-Paket des Frameworks bei und dient gleichzeitig als Kurzreferenz. Code-Schnipsel können direkt per copy & paste in das eigenen Projekt übernommen werden. Dafür steht die Dokumentation zukünftig nur noch in englischer Sprache zur Verfügung. Mir ist es sehr wichtig, eine möglichst gut verständliche und vollständige Dokumentation liefern zu können, weshalb mich in der Vergangenheit immer wieder kleine Unterschiede in den Sprachversionen gestört haben. Die CSS Dateien des Frameworks sind hingegen auch weiterhin überwiegend zweisprachig dokumentiert.

Nun zu den wichtigsten Neuerungen bei YAML selbst. Im März 2011 hatte ich ja bereits über einige der geplanten Änderungen bei YAML 4 gesprochen. Wer die Ankündigungen verfolgt hat, wird über die folgenden Dinge nicht mehr ganz so überrascht sein.

Sublime Text 2 kommt mit einer ganzen Reihe verschiedener Color-Schemes daher. Ich persönlich mag dunkle UIs, weil ich oft bis tief in die Nacht programmiere und kann das Monokai-Theme empfehlen (gibt’s übrigens auch für Coda).

Eines der Highlights des Editors sind die zahlreichen Plugins. Zunächst solltet Ihr Euch aber Package Control installieren, einen bequemen Paket-Manager für Sublime Text 2. Über diesen könnt Ihr dann bequem aus Liste die zu installierenden Pakete auswählen, die Installation geschieht in der Regel vollautomatisch. Als Empfehlung hier eine kleine Auswahl der bei mir installierten Pakete:

• Alignment - erleichtert die Ausrichtung des Quelltextes, z.B. vertikale Ausrichtung an Gleichheitszeichen
• BracketHighlighter - Hervorhebung zusammengehöriger Klammern
• Sublime JSLint - vollautomatisiertes Linting für JavaScript Code aus dem Editor heraus. Bequemer geht es nicht mehr
• Tortoise - Speziell für Windows User interessant, erweitert es den Editor um Menüeinträge und Keyboard-Shortcuts zur Ansteuerung von Tortoise, dem defakto Standard-SVN-Client unter Windows
• Zen Coding - komplexes Plugin zur Code-Vervollständigung für HTML & CSS

JSLint Konfiguration

Obgleich das JSLint Plugin auf Anbieb funktioniert (um eine Java-Runtime braucht man sich nicht kümmern, die kommt gleich mit), ist es dennoch sinnvoll, dem Linter ein wenig Wind aus den Segeln zu nehmen, um nicht von tausenden angeblichen Fehlermeldungen zugeschüttet zu werden. Die Konfiguration erfolgt über ein Config-File, welches man im Editor selbst über Preferences->Package-Settings->JSLint->Settings-Default erreicht.

Unter “jslint_options” kann man hier den Linter entsprechend der eigenen Vorlieben anpassen. Folgende Optionen habe ich gesetzt:

—predef $,document

Wer wie ich viel mit jQuery arbeitet, wird um die Option predef nicht herumkommen. Sie dient dazu, JSLint über globale Variablen zu informieren, auf die der zu prüfende Code zugreift und deren Benutzung somit nicht als Fehler gewertet wird. Für jQuery sind das mindestens $, bzw. jQuery und document.

—white

Ist meinem persönlichen Coding-Stil geschuldet, dass ich nicht von JSLint über die Verwendung von Leerzeichen belehrt werden will.

—browser

Damit werden typische gobale Variablen der Browser verfügbar, z.B. window.

—sloppy

Sollte immer aktiviert werden, solange man noch nicht mit “use strict”; arbeitet.

Das ganze sieht dann fertig so aus:

// Options pass to jslint.
"jslint_options": "--predef $,document --white --sloppy --browser"

Eine vollständige Liste der Optionen gibt es hier. Hat man das hinter sich gebracht, kann man den Linter jederzeit mit Crtl+J anschmeißen und sich anschließend gemütlich durch die Fehlerliste navigieren. So bequem hatte ich es bisher in keinem Editor.

Die Vorgaben des Print-CSS kann ich allerdings weniger empfehlen (ist aber auch weniger dramatisch). Speziell geht es mir um die “Print Friendly Links”, wie es der oben zitierte Beitrag nennt. Hier der betreffende Auszug aus dem HTML5 Boilerplate.

a[href]:after { content: " (" attr(href) ")"; }
abbr[title]:after { content: " (" attr(title) ")"; }
.ir a:after, a[href^="javascript:"]:after,
a[href^="#"]:after { content: ""; } /* Don't show links for images, or javascript/internal links */

Ich habe Vergleichbares (Automatische Auszeichnung von URLs, Akronymen und Abkürzungen) seit vielen Jahren in den YAML Druckstylesheets integriert, allerdings bin ich recht schnell wieder einen Schritt zurück gegangen, indem ich diese Regeln nur noch auskommentiert mitliefere und das aus gutem Grund.

Es ist auf den ersten Blick sicher nachvollziehbar, dass verlinkte URLs beim Druck verloren gehen und man als zuvorkommender Webentwickler diese deshalb hinter dem Linktext mit ausdrucken will, damit für den Anwender der Quellenverweis erhalten bleibt. Doch mal ehrlich: Wie oft hat jeder von Euch im letzten Jahr eine auf Papier abgedruckte URL in den Browser eingetippt? Und wie oft war diese dann länger als 10 Zeichen? Ist die pauschale Ausgabe von URLs also wirklich sinnvoll?

Aus dem anvisierten Komfort für den User wird in der Praxis schnell ein Nerv-Feature – und meist auch der Regelfall. Im Gegensatz zum Print arbeiten wir im Netz nicht mit Quellenverzeichnissen am Ende des Textes, sondern verlinken Schlagworte oder ganze Sätze direkt und im Idealfall auch recht umfangreich. Allerdings steht im Netz die Querverlinkung dem Lesefluss und -genuss auch nicht im Wege. Ausgedruckt ist ein solches Dokument allerdings nur noch bedingt gut lesbar, wenn der Fließtext regelmäßig durch lange, kryptische, nicht umbrechbare URLs unterbrochen wird. Ganz zu schweigen davon, dass sich die Mehrzahl der Anwender eben nicht diebisch darüber freut, eine neue URL zum Abtippen gefunden zu haben.

Gleiches gilt für die Anzeige der title-Attribute von Abkürzungen. Gute Schreibe gebietet, dass Abkürzungen bei ihrem ersten Auftauchen im Text eingeführt/erläutert werden. Aber eben nur beim ersten Mal (vielleicht noch beim zweiten, dann ist aber gut). Das Einpflegen von Akronymen und Abkürzungen erledigt im HTML aber fast niemand von Hand - weil es recht lästig und umständlich ist. Dafür gibt es bei vielen Content Management Systeme entsprechende Plugins, die diese Aufgabe automatisch anhand von Wortlisten übernehmen. Auch daran gibt auf den ersten Blick nichts auszusetzen, denn schließlich wird das title-Attribut nur angezeigt, wenn der Anwender das Element mit der Maus ansteuert und darüber verweilt. Aber schon Nutzer von Screenreadern dürften derartige Automatismen stören, wenn z.B. in einem Webdesign-Fachtext hinter jedem jedem HTML (Hypertext Markup Language) steht/vorgelesen wird. Und Lesern eines ausgedruckten Dokuments geht es da nicht anders.

Die sichtbare Auszeichnung von URLs und Abkürzungen ist per Definition weder unnütz noch schädlich. Allerdings ist sie eben nur dann sinnvoll, wenn die Inhalte entsprechend sorgfältig dahingehend aufbereitet sind, in dem beispielsweise nur die URL von besonders gekennzeichneten Links ausgegeben wird. Genauso wie der Ausdruck der title-Attribute von Abkürzungen nur dann für den User sinnvoll ist, wenn die Texte auch entsprechend sorgfältig aufbereitet werden. Andernfalls kann beides schnell zum billigen Werbefeature des Entwicklers werden, welches u.U. deutlich an den Interessen des Lesers (Internetausdruckers) vorbei geht.

Und so versteckt sich auch im HTML5 Boilerplate die eine oder andere Regel, deren Nutzen mehr Schein als Sein ist, wenn man sie gedankenlos übernimmt.

Das neueste Projekt in dieser Hinsicht ist ein sechsstündiger jQuery Video-Workshop von Gerrit van Aaken, der seit ein paar Tagen bei Undsoversity zum Kauf bereit steht und sich ausdrücklich an Einsteiger richtet. Um sich vor dem Kauf einen Eindruck vom Gebotenen verschaffen zu können, stehen insgesamt drei Kapitel (Events und EventListener, Inline-Bildergalerie und ein interaktiver HTML5-Videoplayer) mit einer Gesamtlänge von fast 2 Stunden (fast 1/3 der Gesamtlänge) kostenfrei auf YouTube bereit.

Aufgebaut sind die einzelnen Themenblöcke als Live-Coding Sessions in denen zu Beginn eine Aufgabe vorgestellt wird, die im Anschluss als “Blick über die Schulter” des Tutors mit HTML, CSS und eben jQuery (Anm: JavaScript sage ich hier bewusst nicht, denn JavaScript scheint kaum thematisiert zu werden) gelöst werden. Die Art und Weise der Präsentation finde ich von Konzept her gelungen und besonders interessant für Autodidakten (wie mich), die lieber durch Probieren als durch dumpfes Lesen neue Dinge lernen. Der Zuschauer kann die schrittweise Entwicklung des Programmcodes anhand konkreter Aufgabenstellungen miterleben und so dessen Logik sehr viel einfacher nachvollziehen, als beispielsweise aus einem spärlich kommentiertem, 2-seitigen Abdruck eines fertigen Quelltextes in einem Buch.

Es ist nicht so, dass es beim Blick auf den Quelltext von Toast nichts zu sagen gäbe. Da wäre zum einen, dass Toast eben nicht, wie fälschlich bei T3N geschrieben, mit einem Standard-Reset daherkommt. Stattdessen setzt man nämlich, und das ist zumindest lobenswert, auf Normalisierung, statt auf Eric Meyers CSS-Dampfwalze, die oft genug in der Kritik stand.

Ein weiteres erwähnenswerte Detail ist der Umstand, dass Toast für seinen flexiblen Grid-Ansatz mal eben auf eines der mit CSS3 neu eingeführten Box-Modelle baut (ohne darauf hinzuweisen, wohlgemerkt). Das macht die Arbeit mit flexiblen Breiten oder unterschiedlichen Einheiten in aktuellen Browsen ausgesprochen angenehm - solange man sich nicht um den Internet Explorer 6 und 7 kümmern muss. Denn diesen dürfte das Grid bei Verwendung irgendeines horizontalen Padding oder Border-Eigenschaft um die Ohren fliegen. Das muss man nicht zwingend negativ sehen, erwähnenswert ist es aber schon (zumal die Codebasis überschaubar ist). Ich persönlich mag da altmodisch denken, aber innerhalb eines Frameworks, halte ich das auch heute mindestens für problematisch, denn die Folgen in alten Browsern können drastisch ausfallen.

Ebenfalls wäre durchaus diskussionsbedürftig, ob es aus Design-Sicht sinnvoll ist, wenn ein CSS-Framework unter “responsive” nichts anderes versteht, als das Grid unterhalb von 775 Pixeln vollständig zu linearisieren (was im übrigen nicht nur Toast, sondern auch andere Projekte betrifft). Aus meiner Sicht stellt sich beispielsweise die Frage, ob ein CSS-Framework für flexible Layouts überhaupt eine solche fixe Grenze vorschreiben sollte? Denn gerade flexible Layouts funktionieren erst richtig gut, wenn man die einzelnen Abstufungen des Layouts individuell auf dessen grafische Elemente abstimmt und sich nicht sklavisch einer fixen Zahl unterwirft, deren Ursprung vor vielen Jahren seine Relevanz verloren hat.

Alle diese Punkte spricht der Beitrag bei T3N aber leider nicht an. Stattdessen bleibt er oberflächlich und nichts-sagend, denn Statements wie “Toast ist nicht für jedes Projekt geeignet. Textlastige Websites können durch den Einsatz des Frameworks an Übersichtlichkeit und Bedienbarkeit gewinnen.” ist ohne Begründung nichts wert. Das eine oder andere wenig technische Detail oder gar eine kritische Anmerkung zur x-ten Kopie der Kopie des Grid-Ansatzes sind offensichtlich zuviel verlangt. Stattdessen werden einfach die Infotexte der Toast-Webseite abgetippt, übersetzt und nicht gerade subtil bebildert - fertig ist der neue Fachbeitrag und genauso schnell sind die Infomeldungen darüber bei Twitter, Facebook, Google+ untergebracht. Dieses Schema taugt auch für die nächsten 50 CSS-Frameworks, soviel ist klar.

Nun, wir haben im deutschsprachigen Raum leider nur eine sehr überschaubare Anzahl von Magazinen, die sich der Frontendentwicklung widmen. Deshalb ich finde es ehrlich gesagt jammerschade, dass die Jungs von T3N sich nicht mehr die Zeit nehmen, den Inhalt der Beiträge vor dem Schreiben genauer unter die Lupe zu nehmen. Hauptsache raus, die gierige Meute im Social-Network-Zirkus will bespaßt werden. Sorry T3N, ihr macht Euch uninteressant und entbehrlich.