html-Dokumentation erstellen

Die Anleitungen für die Schüler werden in einer html-Seitenstruktur aufgebaut.

Zum Einsatz kommen für die Erstellung der Dokumente zwei Werkzeuge: libreoffice als Textverarbeitungsprogramm und docBook zum Erstellen strukturierter Dokumente.

Libreoffice ist frei erhältlich und eine sehr leistungsfähige Bürosuite. Die Textverarbeitung kann html-Seiten erzeugen und pdf-Dokumente ausgeben. Das Problem mit den html-Seiten ist, dass eingebettete Grafiken eigenständig unformatiert werden, und der html-Aufbau  nicht unbedingt den eigenene Vorstellungen entspricht.
Die ersten Versionen der Anleitungen wurden mit diesem Werkzeug erstellt.
Es ist zu empfehlen, dass jedes Dokument in einem eigenen Verzeichnis liegt, und die zugehörigen Grafiken immer als separate Datei noch einmal abgelegt werden. So ist ein späterer Übergang zu einem anderen Werkzeug einfacher möglich.

Docbook ist ein xml-Format. Es wurde zum Erstellen von Büchern, Artikeln, Hilfeseiten entwickelt und trennt Inhalte und Formatierung.
Das Editieren kann in speziellen Editoren erfolgen, jedoch bevorzuge ich die in in eclipse verfügbaren xml-Editoren. Das Ergebnis, also html- oder pdf-Dokumente, sind erst nach einer Generierung verfügbar. Es ist also kein unmittelbarer WYSIWYG-Eindruck verfügbar, was eine gewisse Portion an Geduld und Leidensfähigkeit voraussetzt.

Das Umsetzen der xml-Formate zu html oder pdf erfolgt mit stylesheet-Transformationen (xslt). Das ist ebenfalls in eclipse möglich, die Erstellung der html-Dokumente dauert ca 10 sec.

Der Vorteil ist, dass mit stylesheet-Transformationen die Dokumente weiterbearbeitet werden können und z.B. eine Aufgabenliste erstellt werden kann. Was bei einem ‘unstrukturierten’   Dokument etwas schwieriger ist.

Grafiken werden in gimp bearbeitet oder mit inkscape erstellt. Schaltpläne werde nicht benutzt, da dies in der Alterstufe der Schüler eine Überforderung wäre. Statt dessen wird mit Fritzing ein Verkabelungsplan erstellt.

Gimp ist ein Pixel-Bearbeitungsprogramm. Screenshots können damit bearbeitet, zugeschnitten werden.
Inkscape erstellt Vektorgrafiken in svg-Format. Svg ist ein XML-Format zur Beschreibung von Grafiken. Vorteil ist die Skalierbarkeit ohne Qualitätsverlust. Zum Einbinden in html-Seiten können die Grafiken als Bitmaps ausgegeben werden. Das ist – solange nicht alle Browser SVG einfach unterstützen –  ein praktikabler Weg.

Fritzing ist ein Werkzeug, mit dem Verkabelungspläne erstellt werden können. Diese kann man auch als Schaltpläne interpretieren und sogar als Layout für Platinen ausgeben (was hier im Kurs nicht verwendet wurde).
Ideal ist die realitätsgenaue Darstellung der Bauteile. Das erleichtert den Schülern den Nachbau der Schaltungen.