Dokumentation und Hilfe

Aus Eclipse
Wechseln zu: Navigation, Suche

Generelles

Alle Angaben dieses Artikels beziehen sich auf Eclipse in der Version 3.5 (Galileo - Release). Dieser Release ist bspw. hier erhältlich: download

Dieser Artikel wird sich mit den verfügbaren Möglichkeiten der Dokumentation und Hilfe in Eclipse beschäftigen und in weiterführenden Artikeln kurze Einführungen in die Implementierung der verschiedenen Varianten geben. Passend zum Thema werden diese Einführungen in Form kurzer HowTos abgefasst sein. An den passenden Stellen werden die Anknüpfungspunkte beleuchtet, die einen tieferen Einstieg in die Materie ermöglichen.

Definition und Arten von Dokumentation in Eclipse

Definition: Dokumentation von Softwaresystemen

Softwaresysteme können in der Regel als technische Erzeugnisse betrachtet werden. Die Dokumentation eines Softwaresystems ist also grundsätzlich der Klasse der technischen Dokumentation zuzuordnen. Diese ist nach der Definition für technische Dokumentation in wikipedia "die Gesamtheit von Dokumenten, die ein technisches Erzeugnis beschreiben". Diese Gesamtheit besteht aus verschiedensten Dokumententypen, die meist durch eine Richtlinie, oder Norm definiert werden. Beispielsweise gibt es die Europäische Norm EN 62079 für "das Erstellen von Anleitungen - Gliederung, Inhalt und Darstellung".

Technische Dokumentation kann auch in verschiedensten Ausprägungen vorkommen, sowohl als statische Papier-Dokumente, wie zum Beispiel Printerzeugnisse, Notizen und Zeichnungen, als auch als elektronische Dokumente, wie zum Beispiel eine Online Hilfe.

Entscheidend für den Typ und die Ausprägung des zu erzeugenden Dokumentes ist die Zielgruppe, für die das Dokument verfasst wird. Dabei gibt es nach der Norm VDI 4500 die sogenannte interne Dokumentation, welche primär für den Hersteller des Erzeugnisses gedacht ist und Maßnahmen der Weiterentwicklung, Fehlerbeseitigung und der Qualitätssicherung unterstützt, als auch die sogenannte externe Dokumentation, die an den Benutzer eines Erzeugnisse gerichtet ist und beispielsweise seine Nutzung erklären soll. Beispiele für interne Dokumentation sind:

  • UML-Diagramme
  • Textuelle Spezifikationen
  • Pflichtenhefte
  • Kommentare im Code
  • Der Code selbst

Auf die interne Dokumentation eines Plug-Ins wird im Rahmen dieses Artikels nicht weiter eingegangen. Für mehr Informationen hierzu sei auf die Richtlinie VDI 4500 verwiesen. Dieser Artikel wird sich hauptsächlich mit der elektronischen externen Dokumentation eines Eclipse-Plug-Ins und Ihrer Erstellung beschäftigen.

Externe Dokumentationsmöglichkeiten in Eclipse

Folgende Arten elektronischer externer Dokumentation stehen Autoren eines Eclipse - Plug-Ins in der Eclipse Plattform zur Verfügung:

Online Hilfe

Laut der Wictionary Definition für Hilfe ist Hilfe ein "Programm[1] oder Programmteil, in dem Erläuterungen zu einer bestimmten Sache oder dem Programm stehen". Diese Definition ist nicht ganz korrekt, da die Erläuterungen meistens in den sogenannten Hilfedateien stehen, die streng genommen keine Programme oder Programmteile sind. Da die Implementierung einer Online-Hilfe für ein Eclipse Plug-In in Form eines eigenen Plug-Ins aber einen gewissen Programm-ähnlichen Charakter bekommt ist die Definition zumindest in Teilen anwendbar.

Eclipse bietet drei verschiedene Möglichkeiten an, Hilfedokumente zu visualisieren:

Helpview

Eclipse bietet einen Helpview an, der sich in die Eclipse Workbench integriert und somit sämtliche Dockingmöglichkeiten zulässt. Hier werden verschiedene Möglichkeiten angeboten, in der Hilfe-Dokumentation zu recherchieren. So kann man entweder den definierten Index zur Schlagwortsuche nutzen, im Inhaltsverzeichnis navigieren, oder aber die Suche mit verschiedenen Ausdrücken konsultieren. Die Suche bietet auch mehrere Möglichkeiten, die Ergebnisse einzuschränken, so bedeutet bspw. das Einschließen in doppelte Anführungszeichen, dass der Suchausdruck exakt gefunden werden soll

Integrierter Helpview in Eclipse

Der Helpview wird beispielsweise durch einen Klick auf Dynamic Help im Menü Hilfe geöffnet, oder durch einen Druck auf die Taste F1.

Helpwindow

Eine weitere Möglichkeit, sich Hilfe-Inhalte anzeigen zu lassen ist, ein separates Helpwindow zu benutzen. Dieses wird durch einen Klick auf Help Contents im Menü Hilfe geöffnet.

Hilfe als eigenes Fenster

Der Vorteil gegenüber dem in die Workbench integrierten Helpview ist, dass, wenn man die Anzeige der Hilfe einem eigenen (und dann vom Betriebssystem verwalteten) Fenster überlässt, man auch andere, nicht in Eclipse integrierte Programme parallel dazu verwenden kann, ohne mit dem ganzen Eclipse-Fenster jonglieren zu müssen. Wenn man zum Beispiel zu einem Hilfepunkt zusätzliche Informationen im Internet recherchieren möchte, kann es sinnvoll sein, nur das Hilfefenster zusätzlich auf dem Desktop zu haben und nicht die ganze Eclipse Oberfläche, in der ein Fenster die Hilfe anzeigt. Von der Funktionalität sind beide Varianten, Hilfe im Fenster und Hilfe im View ähnlich, der Helpiew ist durch seine Kompaktheit etwas umständlicher zu bedienen. So hält das Helpwindow einen eigenen Fensterbereich vor, um den Index, die Inhalte, Suchergebnisse und Bookmarks anzuzeigen, im Helpview werden die Inhalte in einem Fenster umgeschaltet.

Helpview verglichen mit Helpwindow

Infopops

Infopops sind eine weitere Möglichkeit, dem User in Eclipse Hilfe anzubieten. Infopops können, genauso, wie der interne Helpview aktiviert werden, indem dem UI-Element von Interesse der Fokus gegeben wird (bspw. durch Klick, oder wechseln zu diesem Element mittels Shortcut) und anschließendem Druck auf die F1-Taste. Infopops stellen in der Eclipse-Hilfe-Struktur eine Art Vorstufe und Kompaktifizierung des im Helpview angezeigten Hilfetextes dar.

Das Infopop bietet somit, neben kurzen Informationen zu dem entsprechenden Element die Möglichkeit, weitere Informationen aus der Online-Hilfe abzurufen.

Ein Infopop

Ob sich beim Druck auf F1 der Helpview öffnet, oder zunächst ein InfoPop kann man in der Help-Sektion der Eclipse Preferences festlegen.

Voreinstellungen ob F1 Helpview oder Infopop öffnet

Sowohl Helpview, als auch die Infopops sind, im Gegensatz zum Helpwindow kontextsensitiv.

Tooltips

Tooltips sind eine weitere Variante der externen Dokumentation. Mit Tooltips kann dem User auf unkomplizierte Art ein Hinweis gegeben werden, was das Control bewirkt, über dem der Mauszeiger gerade steht. Auch Eclipse bietet selbstverständlich die Möglichkeit, Tooltips zu implementieren.

Ein Tooltip in Eclipse

Cheat Sheets / Tutorials

Auf wikipedia findet sich eine gute Definition des Computer-Fachbegriffs Tutorial. Hier wird ein Tutorial als filmische oder schriftliche Gebrauchsanleitung für ein Computerprogramm bezeichnet. Nach dieser Definition lassen sich auch die in Eclipse verwendeten Cheat Sheets den Tutorials zuordnen.

Der Ausdruck Cheat Sheet leitet sich dabei vom englischen "to cheat" - "betrügen" und "sheet" - "Blatt" ab und bezeichnet eine Schritt-für-Schritt Anleitung, die es dem Neuling ermöglicht, die beschriebene Eclipse-Funktionalität schnell zu erlernen. Das Cheat Sheet aus Eclipse ist dabei eine gute Möglichkeit in der Plattform selber ein Tutorial für eine Funktion der Plattform zu entwickeln. Ein Cheat Sheet lässt sich öffnen, indem man zunächst im Help Menü den Punkt Cheat Sheets... auswählt. Nun erscheint ein Auswahlfenster:

Das Cheet Sheet-Auswahlfenster

Wählt man in diesem Fenster ein Cheat Sheet aus und startet es, so öffnet sich der Cheet Sheet-View, in dem man Schritt für Schritt zum gewünschten Ergebnis geführt wird:

Das Cheat Sheet

Die Cheat Sheets in Eclipse sind vergleichsweise statisch, ohne Animationen angelegt. Dadurch können sich noch Missverständnisse einschleichen, beispielsweise welcher Button gemeint ist, wenn der Autor des sheets nicht sauber gearbeitet hat. Hier bietet sich noch Potential für eine zukünftige Weiterentwicklung von Eclipse.

Wizards

Wizards können ebenfalls zur Dokumentation gerechnet werden, da sie einen Vorgang im Programm beschreiben und unterstützen. Zum Thema Wizards und Ihrer Anwendung wird auf diesen Artikel auf der gleichen Seite verwiesen:

Ein Artikel zu Wizards findet sich hier: Wizards

Branding

Als Branding wird das "Brandmarken" des Produkts, als das eigene bezeichnet. Siehe dazu auch: wikipedia.

Aboutscreen

Speziell im kommerziellen Bereich hat das Branding von Programmen einen hohen Stellenwert, da hiermit nicht nur die Urheberschaft, sondern auch die Lizenzierungsart festgelegt wird. Gerade bei einem Tool wie Eclipse, an dem viele verschiedene Hände mitwirken ist es umso wichtiger für den einzelnen, der bspw. ein kommerzielles Plug-In vertreiben will, eine Stelle zu haben, an der seine Ansprüche an den Nutzer des Plug-Ins offenbar werden.

Eclipse bietet hierfür einen zentralen Platz an, an dem alle eingebundenen Plug-Ins, mitsamt deren Urhebern und Lizenzdokumenten einsehbar sind. Hierfür ist es zunächst notwendig, die Art der Plug-In-Organisation in Eclipse noch einmal kurz zu beleuchten:

Plug-Ins sind die kleinste Einheit bei der Plug-In-Entwicklung in Eclipse. Jedes Plug-In kann über seine Manifest-Datei mit Branding - Informationen versehen werden.

Features sind die Möglichkeit in Eclipse mehrere Plug-Ins zu bündeln und gemeinsam auszuliefern. Wenn man die Hilfe für sein selbstgeschriebenes Plug-In in die Eclipse-Hilfe integrieren möchte (als eigenständiges Plug-In), so kommt man, sofern man einen geregelten Auslieferungs-Vorgang wünscht, nicht um die Erstellung eines Features aus beiden Plug-Ins herum, da man nur so mehrere Plug-Ins definiert zusammenfassen kann. Sofern man seine Plug-Ins online (bspw. über Eclipse-update) ausliefern möchte, sollte man ebenfalls ein Feature erstellen.

Alle Feature- und Plug-In-Informationen sind zentral über den About-Dialog von Eclipse erreichbar. Wenn man nun in Eclipse im Menü Help auf den Button About klickt, so sieht man zunächst den zentralen About Dialog der Eclipse Plattform:

Zentraler Aboutdialog in Eclipse

Hier kann man schon (an Hand der Icons) einige der installierten Features erkennen. Sofern im Branding-Plug-In eines Features ein Icon definiert ist, wird es hier angezeigt. Geht man nun einen Schritt weiter und klickt auf eines der Icons, gelangt man zur Detail-Seite des jeweiligen Features auf der man die Details zum Feature selbst und seine zugehörigen Plug-Ins sehen kann:

Feature Details zur Eclipse Plattform

Von hier aus kann man sich nun noch die details zum jeweiligen Plug-In anzeigen lassen (bspw. durch Doppelklick auf den Plug-In-Namen):

Die Plug-Ins eines Features

Von hier aus kann man sich schließlich noch die konkreten Lizenz-Informationen zum jeweiligen Plug-In anzeigen lassen, die in Form einer HTML-Seite hinterlegt sind:

Ein Plugin-Lizenz-Dokument

Updatesites

Wie im vorherigen Absatz angesprochen kann man das Anlegen eines Features auch dafür nutzen, ein Plug-In online zur Verfügung zu stellen, was es sowohl dem Entwickler, als auch dem Nutzer wesentlich vereinfacht, sein Plug-In auf dem aktuellen Stand zu halten, oder aber auch ein passendes Plug-In für eine neue Aufgabe zu finden. Dazu bietet Eclipse im Help-Menü die beiden Punkte check for Updates und Install New Software... an.

Der Punkt check for Updates nutzt eine in der Feature-Definition hinterlegte URL, um vollautomatisch nach einer aktuelleren Version des Features zu suchen, diese herunterzuladen und zu installieren.

Eclipse beim vollautomatischen Update

Zusammenfassung und Ausblick

Eclipse hat sich in der Galileo - Version 3.5 zu einem extrem mächtigen und gleichzeitig gut bedienbaren Werkzeug entwickelt. Die Komplexität, die früheren Versionen von Eclipse bei der breiteren Verteilung im Wege stand, wurde durch zahlreiche neue Wizards und einen stetigen Ausbau der Dokumentation sowie durch zielgruppengerechte Sekundärliteratur weitestgehend aufgefangen. Nun ist es auch ohne tiefschürfende Kenntnisse der Plattform selbst möglich Erweiterungen dafür zu entwickeln. Wie bei jedem immer in Entwicklung befindlichen Software-Projekt, so lassen sich auch bei der Eclipse Plattform kleinere Inkonsistenzen von neuen Features und Ihrer Umsetzung nicht immer vermeiden. So führt bspw. der Wizard für eine Update-Site beim Einsatz von Plattform-Spezifika im Feature zu einer nicht nutzbaren Update Site, das Feature selbst ist dann ebenfalls bei einer lokalen Installation nicht voll nutzbar. Das sind aber kleinere Fallstricke in einer ansonsten sehr stabilen und gut nutzbaren Plattform. Jedes neuere Feature bringt immer ebenfalls eine Wunschliste mit neuen Ausprägungen des Features, bzw. neuen "Features des Features" mit sich. So wäre es bspw. sehr schön, wenn die Cheat Sheets, die ja eine schnelle Schritt-für-Schritt Anleitung sein sollen Möglichkeiten mitbringen würden, dem User eindeutiger zu zeigen, wie sich automatisch ausgeführte commands (bspw. das Wechseln des Views) und manuell ausgeführte Aktionen in der Oberfläche finden lassen (zum Beispiel über einen "Show me where..." Button, der den Mauszeiger zu der Stelle führt, wo geklickt werden muss). Der Lerneffekt ließe sich dadurch steigern und neue Zielgruppen (bspw. die der unbedarfteren Anwender) erschließen.

Weiterführende Artikel

Der vorangegangene Überblick über die in Eclipse enthaltenen externen Dokumentationsmöglichkeiten ist zwar nicht abschließend, die meisten und meistverwendeten Angebote sind jedoch beleuchtet worden. Für einen tieferen Einstieg sei auf die Sektion Offline-Literatur im Artikel Links und Literatur zu Hilfe verwiesen. In den folgenden Artikeln wird auf die konkrete Implementierung der jeweiligen Dokumentationsart in Form kurzer HowTos eingegangen. Der Artikel Links und Literatur zu Hilfe enthält eine kleine Sammlung von Verweisen auf weiterführende Literatur.