Durchsuchbare Dokumentation aufrufen
Zurück zur Dokumentationsübersicht
Dokumentationen erstellen
Hinweis: Diese Dokumentation bezieht sich auf die aktuellste Version des Plug-ins. Aktualisieren Sie das hier beschriebene Plug-in, um die Dokumentation verwenden zu können.
Grundgerüst des Dokumentationssystems
Eine Dokumentation besteht aus:
- HTML-Dateien
- Bildern
- Videos
- Verweisen auf andere HTML-Dokumente
Den Dokumentationsbereich öffnen
Eine Dokumentation legen Sie in einem definierten Bereich innerhalb von agorum core ab. Dazu öffnen Sie den Dokumentationsbereich.
- Klicken Sie oben rechts in der Kopfleiste auf
und dann auf Dokumentationsbereich öffnen.
Ergebnis: Der Dokumentationsbereich öffnet sich. Sie sehen drei Ordner:
• intern
• partner
• public
Diese Bereiche definieren, wer die Dokumentationen lesen kann. Die Bereiche können bei Ihnen unterschiedlich lauten, je nachdem, was Ihr Administrator eingerichtet hat. Sprechen Sie ihn ebenfalls darauf an, wenn Sie wissen wollen, wer worauf Zugriff hat.
Dokumentationen strukturieren
Dokumentationen aus Vorlagen anlegen
Für die Strukturierung der Dokumentationen bietet das Dokumentationssystem Vorlagen an, mit denen Sie Ihre Dokumentationen strukturieren können. Wenn Sie eine Vorlage anlegen, fasst das System alle Dokumentationen und Medien in einer Ordnerstruktur zusammen.
Tags verwenden
Eine Strukturierung können Sie auch durch Tags vornehmen, mit denen Sie Ihre Dokumentationen Themen zuordnen. Sie können beliebige Tags zu einer Dokumentation vergeben. Diese Tags verwendet das System für eine Strukturierung nach Tags, sodass Ihre Dokumentation bei den Themen erscheint, die Sie getagt haben.
Neu vergebene Tags erscheinen nicht sofort in der Tag-Übersicht. Damit Tags dort erscheinen, müssen Sie die Tag-Übersicht manuell erstellen oder bis zum nächsten Tag abwarten, da das System erst nachts automatisch eine solche Tag-Übersicht und ein Dokument mit dem Namen tag-overview.html erstellt.
Alternativ können Sie dieses Dokument als Einstiegsdokument festlegen, indem Sie es etwa direkt unterhalb des Bereichs public platzieren. Die Einstellung nimmt Ihr Administration vor.
Überschriften verwenden
Eine weitere Möglichkeit der Strukturierung ist die Platzierung von Überschriften innerhalb einer Dokumentation. Diese Überschriften reichen von Überschrift 1 (H1) bis Überschrift 3 (H3).
Verweise verwenden
Sie können zusätzlich auf weitere Dokumentationen verweisen, die Sie erstellt haben. Auch diese Dokumentationen zieht das System zur Strukturierung heran.
Die Baumstruktur verstehen
In der Dokumentationsansicht sehen Sie links eine Baumstruktur, die Ihre Dokumentationen widerspiegelt. Die Baumstruktur können Sie auf- und zuklappen.
Diese Baumstruktur baut das System automatisch auf, indem es die gesamte Struktur von verwiesenen Dokumentationen durchgeht.
Für eine Dokumentation gilt für den Anzeigenamen, den Sie links in der Baumstruktur sehen, folgende Regeln:
- Wenn Sie einen Anzeigenamen unter Verlinkte Dokumentationen auf dieser Seite des Dokumentationseditors vergeben haben, verwendet das System diesen Namen.
- Wenn Sie unter Verlinkte Dokumentationen auf dieser Seite des Dokumentationseditors keinen Anzeigenamen eingetragen haben, jedoch einen Anzeigenamen im Bereich Eigenschaften dieser Dokumentation vergeben haben, verwendet das System diesen Anzeigenamen.
- Wenn weder 1. noch 2. zutreffen, verwendet das System die erste Überschrift Überschrift 1 (H1) für die Darstellung des Anzeigenamens in der Baumstruktur.
Eingerückt folgen die weiteren Überschriften aus der Dokumentation. Unterhalb der Überschriften folgen wiederum verwiesene Dokumentationen, für die wieder die gleichen Regeln gelten.
So starten Sie am effektivsten
Bevor Sie mit Ihrer Dokumentation beginnen, stellen Sie sich diese Fragen:
- Was möchten Sie dokumentieren?
- Wer soll die Dokumentation lesen?
- Was möchten Sie mit der Dokumentation erreichen?
- Wie möchten Sie die Dokumentation strukturieren?
Teilen Sie Ihrem Administrator auch mit, dass er die einzelnen Bereiche vor Beginn bereits mit Startdokumenten versehen haben muss. Diese Dokumente bestimmen, wie die Dokumentation beginnt, wenn ein Benutzer einen der Bereiche der Dokumentation öffnet.
Ein Benutzer öffnet etwa den öffentlichen Bereich über Ihre für alle zugängliche Webseite; den Partner-Bereich öffnet ein angemeldeter Partner etwa über einen separat zugänglichen Bereich auf Ihrer Webseite. Alle drei Bereiche (intern, partner und public) können Sie in agorum core öffnen, sobald Ihr Administrator die Einstellungen dazu vorgenommen hat.
Wer soll die Dokumentation lesen?
Diese Frage entscheidet, wo Sie die Dokumentation ablegen. Sie können die Dokumentation jederzeit auch in andere Bereiche verschieben, wenn sich die Anforderungen dafür ändern. Sie können etwa zuerst intern beginnen und die gesamte Dokumentation zur Veröffentlichung in den öffentlichen Bereich (public) verschieben.
Wie möchten Sie die Dokumentation strukturieren?
Sie möchten ein neues Thema beginnen. Gehen Sie wie folgt vor:
In dem Bereich, für den Sie sich entschieden haben, legen Sie eine Vorlage an, damit Sie aus diesen später Ihre Dokumentation erstellen können.
Alternativ bauen Sie die Grundstrukturierung Ihrer Dokumentation über Tags auf. Dann müssen Sie sich Gedanken darüber machen, wie Ihre Tags lauten. Die Tag-Struktur können Sie als Tag-Übersicht erstellen.
Aktionen im Dokumentationssystem ausführen
Innerhalb eines Dokumentationsbereichs (public, intern, partner) können Sie bestimmte Aktionen mithilfe der rechten Maustaste und des Kontextmenüs ausführen.
Eine Dokumentation (HTML-Dokument) anlegen
| Aktion | Beschreibung |
|---|---|
| Neu > Dokumentation (HTML-Dokument) | Legt eine neue Dokumentation in Form eines HTML-Dokuments innerhalb des gewählten Ordners an. |
Eine Dokumentation (aus Vorlage) anlegen
| Aktion | Beschreibung |
|---|---|
| Neu > Dokumentation (aus Vorlage) | Legt eine neue Dokumentation aus einer Vorlage an inklusive Unterordner für Medien. |
Hinweis: Benötigen Sie weitere Vorlagen, wenden Sie sich an Ihren Administrator.
Eine Vorlagenkategorie anlegen
| Aktion | Beschreibung |
|---|---|
| Neu > Dokumentation - Vorlagenkategorie | Legt innerhalb einer Vorlage eine neue Kategorie an. |
Hinweis: Benötigen Sie weitere Vorlagenkategorien, wenden Sie sich an Ihren Administrator.
Eine Tag-Übersicht erstellen
| Aktion | Beschreibung |
|---|---|
| Dokumentation > Tag-Übersicht hier erstellen | Erstellt innerhalb des gewählten Bereichs (öffentlich, intern, partner) eine Tag-Übersicht. Diese Tag-Übersicht enthält alle Dokumentationen mit Tags, die unterhalb des gewählten Bereichs zu finden sind. |
- Setzen Sie den Haken bei Tag-Übersicht erstellen, erstellt das System jede Nacht automatisch eine neue Tag-Übersicht, sofern sich Tags geändert haben.
- Nach Erstellen der Tag-Übersicht legt das System im gewählten Ordner ein HTML-Dokument mit dem Namen tag-overview.html ab.
- Das HTML-Dokument tag-overview.html öffnet sich im Dokumentationseditor, sodass Sie es bearbeiten können.
Alle Dokumente ohne Tags fasst das System am Ende in der Überschrift (ohne Tags) zusammen.
Dokumentationen suchen und verschieben
| Aktion | Beschreibung |
|---|---|
| Dokumentation > Dokumentationen suchen und hierhin verschieben | Strukturiert Dokumente manuell neu. |
Nachdem Sie die Aktion durchgeführt haben, öffnet sich die Suche. Suchen und wählen Sie hier Ihre Dokumentationen aus und klicken Sie auf OK, um sie in den Ordner abzulegen, aus dem Sie die Aktion gestartet haben. Die Aktion selbst blendet den Ordner aus, in dem Sie diese Aktion gestartet haben.
Alle verwendeten Medien des Kapitels sammeln
| Aktion | Beschreibung |
|---|---|
| Dokumentation > Alle verwendeten Medien der Vorlage sammeln | Verschiebt/ sammelt alle Medien innerhalb einer Vorlage in den Ordner Medien.
|
Medien sind Bilder, Hardcopys und auch Videos, die Sie in agorum core ablegen. Diese Medien können Sie in Dokumentation verknüpfen, sodass das System diese dort anzeigt.
Alle verwiesenen Dokumentationen sammeln
| Aktion | Beschreibung |
|---|---|
| Dokumentation > Alle verwiesenen Dokumentationen sammeln | Sammelt/ verschiebt alle Dokumentationen, die in der gewählten Dokumentation verknüpft sind, in das ausgewählte Kapitel. Um die Aktion zu wählen, markieren Sie ein HTML-Dokument in einer Vorlage. |
Diese Aktion verschiebt alle Dokumentationen, die in der gewählten Dokumentation verknüpft sind, in die gewählte Vorlage, um alle verstreuten Dokumentationen im Dokumentationssystem an einem gemeinsamen Ablageort zu sammeln.
Für das Verschieben gelten diese Regeln:
- Wenn eine Dokumentation in einer anderen Vorlage liegt, verlinkt das System diese Dokumentation, verschiebt sie jedoch nicht. Sie benötigen den Link etwa, damit die Dokumentation dann das entsprechende Recht erhält, etwa wenn sich eine Dokumentation im Bereich intern befindet, sie aber zusätzlich noch in einer anderen Dokumentation verwiesen ist.
- Wenn eine Dokumentation unterhalb des Dokumentationssystems liegt, dort aber nicht in einer Vorlage, verschiebt das System diese Dokumentation.
- Wenn eine Dokumentation außerhalb des Dokumentationssystems liegt, verlinkt das System diese Dokumentation, verschiebt sie aber nicht. Sie benötigen den Link etwa, damit die Dokumentation dann das entsprechende Recht erhält, etwa wenn sich eine Dokumentation im Bereich intern befindet, sie aber zusätzlich noch in einer anderen Dokumentation verwiesen ist.
Mit dem Dokumentationseditor arbeiten
Der Dokumentationseditor unterstützt Sie bei der Erstellung von Dokumentationen. Mit dem Editor können Sie:
- Titel und Name der Dokumentation anpassen
- Verknüpfungen erstellen
- Einstellungen für die Darstellung in der Baumstruktur vornehmen
- diverse Aktionen durchführen, etwa Bilder und Videos einfügen
Sie starten den Dokumentationseditor auf zwei Arten:
- automatisch, wenn Sie eine neue Dokumentation anlegen
- manuell, indem Sie im Dokumentationsbereich einen Doppelklick auf ein HTML-Dokument ausführen
Der Dokumentationseditor besteht aus diesen Abschnitten:
- Eigenschaften dieser Dokumentation
- Aktionen
- Versionen
- Verlinkte Dokumentationen auf dieser Seite
- Verlinke Medien auf dieser Seite
- Enthalten in diesen Übersichten
- Änderungshistorie
Abschnitt „Eigenschaften dieser Dokumentation“
In diesem Abschnitt geben Sie Eigenschaften zur gewählten Dokumentation ein.
Ist eine Dokumentation nur ab einer bestimmten Version oder bis zu einer bestimmten Version gültig, zeigt das System diesen Hinweis direkt unter diesem Abschnitt an.
| Feld / Einstellung | Beschreibung |
|---|---|
| Name | Definiert den Namen der Dokumentation.
|
| Anzeigename | Definiert den Anzeigenamen der Dokumentation. Den Anzeigenamen zeigt das System in der Baumstruktur an, wenn Sie auf diese Dokumentation in einer anderen Dokumentation verweisen. |
| Baumstruktur aus H1-, H2- und H3-Überschrift erstellen | Stellt in der Baumstruktur die Überschriften (Überschrift 1 (H1), Überschrift 2 (H2) und Überschrift 3 (H3)) dar. Beispiel
Verwenden Sie in Ihrer Dokumentation mehrfach eine Überschrift 1 (H1), zeigt das System in der Baumstruktur nur die erste Überschrift 1 an. Alle weiteren Überschriften 1 interpretiert es als Überschrift 2.
|
| Neue Übersicht ab hier erstellen (nachts) | Erzeugt automatisch jede Nacht ab dieser Dokumentation eine neue Übersichtsdokumentation.
|
| Beschreibung | Definiert eine Beschreibung für die Dokumentation.
|
| Sprache | Versieht die Dokumentation mit einer Sprache, sodass Sie mehrere Sprachversionen für eine Dokumentation erstellen können. Das System übersetzt die Dokumentation nicht automatisch. Sie selbst müssen die Dokumentation in die jeweilige Sprache übersetzen. Mehr zu Sprachen siehe Mit Sprachen im Dokumentationssystem arbeiten. |
| Globale Tags | Versieht die Dokumentation mit Tags und listet die Dokumentation in der Tag-Übersicht unter diesen Tags auf. Auch die Tags berücksichtigt das System bei der Suche in die Relevanz der Ergebnisliste. |
| Bereich | Definiert den Bereich, in dem die Dokumentation liegt (intern, öffentlich, partner) inklusive Ablageort der Dokumentation innerhalb des Bereichs.
|
Achtung: Beeinträchtigung der Systemleistung durch Aktualisierung der Struktur. Die Generierung der Übersicht belastet das System, es kann daher an anderen Stellen im System zu Verzögerungen kommen. Führen Sie die manuelle Generierung nur durch, wenn niemand mit agorum core arbeitet.
Rechts neben der Einstellung Neue Übersicht ab hier erstellen (nachts) können Sie über 
die Übersicht manuell erzeugen. Das System ändert alle untergeordneten Dokumentationen dieser Dokumentation in der Baumstruktur in ihrem Titel ab, sofern Sie ihn zuvor angepasst haben. Alle Dokumente, die sich oberhalb befinden, passt das System nicht an.
Beispiel
Sie befinden sich in der Dokumentation Übersicht - agorum core basic archive.html und haben zuvor die Seite Übersicht - agorum core basic archive fileserver integration.html im Titel verändert. Sie möchten nun, dass sich der Titel auch in der Baumstruktur verändert. Dazu müssen Sie die Übersichtsseite des internen Bereichs öffnen (Dokumentation Einstieg - Intern.html) und dort die Generierung anstoßen, da die Seite Übersicht - agorum core basic archive fileserver integration.html eine Unterseite von Übersicht - agorum core basic archive.html und diese wiederum eine Unterseite von Dokumentation Einstieg - Intern.html ist.
Würden Sie die Generierung der Übersicht lediglich von der Seite Übersicht - agorum core basic archive.html anstoßen, ändert sich der Titel in der Baumstruktur auch nur in dieser Ansicht. Der Titel wäre in der Gesamtübersicht allerdings immer noch unverändert.
Im Hintergrund erzeugt das System einmal alle 24 Stunden (nachts) automatisch eine neue Übersichtsstruktur, sodass Änderungen unterhalb der Struktur am nächsten Tag automatisch aktiv sind.
Abschnitt „Aktionen“
siehe Aktionen im Dokumentationssystem
Abschnitt „Versionen“
Siehe Mit Versionen im Dokumentationssystem arbeiten.
Abschnitt „Verlinkte Dokumentationen auf dieser Seite“
In diesem Abschnitt zeigt das System alle verlinkten Dokumentationen in agorum core an, die in dieser Dokumentation enthalten sind.
- Über die Einstellung Folgen stellt das System diese Dokumentation in der Baumstruktur dar (nach dem automatischen nächtlichen Durchlauf).
- Über das Feld Anzeigename steuern Sie den Namen der Dokumentation in der Baumstruktur. Wenn Sie das Feld nicht befüllen, nimmt das System den Text als Anzeigenamen.
Abschnitt „Verlinkte Medien auf dieser Seite“
In diesem Abschnitt zeigt das System alle verlinkten Medien (Bilder, Videos) an, die in dieser Dokumentation enthalten sind.
Abschnitt „Enthalten in diesen Übersichten“
In diesem Abschnitt zeigt das System alle Dokumentationen an, in denen die aktuell geöffnete Dokumentation verlinkt ist. Aus dieser Liste heraus können Sie die entsprechende Dokumentation bearbeiten oder direkt die Übersicht aufrufen.
Abschnitt „Änderungshistorie“
Wenn Sie für längere Zeit an einer Dokumentation arbeiten, können Sie sie in diesem Abschnitt als Arbeitskopie auschecken. Damit bleibt die aktuelle Dokumentation auf dem Stand, wie sie ist, bis Sie Ihre Bearbeitung abgeschlossen haben.
Sobald Sie mit der Änderung fertig sind, können Sie die Dokumentation wieder einchecken. Das System führt diese Dokumentation als Haupt-Dokumentation.
Verschiedene Dokumententypen existieren:
| Dokumententyp | Beschreibung |
|---|---|
| Aktuell | Aktuelle Version der Dokumentation. Pro Dokumentation existiert nur einmal der Typ Aktuell. |
| Arbeitskopie | Ausgecheckte Version der Dokumentation.
|
| Historie | Vergangene Versionen der Dokumentation.
|
Der HTML-Editor
Im HTML-Editor erstellen Sie den Inhalt Ihrer Dokumentation. Sie fügen dort Ihren Text ein oder formatieren ihn.
Tipp: Die Überschriftsebenen können Sie auch per Tastenkombination erreichen:
1. Überschriftsebene
STRG+1
2. Überschriftsebene
STRG+2
3. Überschriftsebene
STRG+3
Normales Absatzformat
STRG+0
Den Anker verwenden
Den Anker fügen Sie oben im Menü über 
=> Anker ein. Er dient dazu, in einer Dokumentation zu einer anderen Stelle zu springen, etwa, wenn sich Ihr Leser im Fließtext befindet und zu einer thematisch wichtigen Überschrift in der gleichen Dokumentation springen soll (parallel zum Querverweis in etwa Microsoft Word).
- Verwenden Sie als Ankernamen nur Buchstaben (A bis Z, a bis z) sowie alphanumerische Zahlen (0 bis 9).
- Sonderzeichen, Umlaute und Leerzeichen sind nicht erlaubt.
Mit Filtern nach Dokumentationen suchen
Das Dokumentationssystem liefert den Filter Dokumentation für die Suche mit. Mit diesem Filter suchen und finden Sie bestimmte Dokumentationen schneller.
Suchoptionen
| Suchoption | Beschreibung |
|---|---|
| Übersichtsdokumentationen (auto) | Zeigt alle Dokumentationen an, die im Abschnitt Eigenschaften dieser Dokumentation die Einstellung Neue Übersicht ab hier erstellen (nachts) gesetzt haben. |
| Tag Übersichten (auto) | Zeigt alle Dokumentationen an, für die das System jede Nacht eine Tag-Übersicht erstellt. |
| Verwaiste Links | Zeigt alle Dokumentationen an, in denen Verweise auf Dokumentationen enthalten sind, die nicht mehr existieren. Laden Sie diese Dokumentationen und prüfen Sie im Abschnitt Verlinkte Dokumentationen auf dieser Seite, welcher Link keinen Bereich mehr besitzt. Hier zeigt das System unbekannt an. |
| Dokumentationen ohne Übersicht | Zeigt alle Dokumentationen an, die keine direkte Übersicht besitzen. Im Normalfall sind dies die meisten Dokumentationen, da nur bestimmte Dokumentationen, etwa eine Einstiegsdokumentation, eine Übersicht haben. |
| Enthalten in Übersicht | Zeigt alle Dokumentationen an, die in einer bestimmten Übersichtsdokumentation verlinkt sind. Wählen Sie nach Auswahl dieser Suchoption die Übersichtsdokumentation in der Liste. |
| Ausgecheckt | Zeigt alle Dokumentationen, die aktuell ausgecheckt sind. |
Darstellung der Suchergebnisse
In der Dokumentationsansicht können Sie und andere Benutzer nach Dokumentationen suchen, um die gewünschte Dokumentation zu finden.
Die Ergebnisliste stellt das System nach Relevanz der Treffer dar. Die Relevanz hat folgende Schwerpunkte, die in der Sortierung maßgeblich sind. Die folgende Liste ist absteigend nach Relevanz sortiert:
- Treffer im Namen der Dokumentation
- Treffer in der Beschreibung der Dokumentation
- Treffer in den Tags, die die Dokumentation besitzt
- Treffer im Inhalt der Dokumentation
- Wenn Sie mehrere Suchwörter eingegeben, vergrößert sich die Relevanz, wenn diese enger zusammenstehen
Hinterlegen Sie bestimmte Wörter im Namen oder in der Beschreibung, zeigt das System diese Dokumentation an oberster Stelle im Suchergebnis an, wenn im Name oder in der Beschreibung Treffer enthalten sind.
Eine Dokumentation löschen
Wichtig: Löschen Sie eine Dokumentation nicht, sofern diese mehrere Versionen hat und diese Dokumentation die ursprüngliche Dokumentation ist, auf der die anderen Dokumentationen aufbauen. Das System kann sonst alle Versionen dieser Dokumentation nicht mehr korrekt anzeigen, wenn diese in anderen Dokumentationen verlinkt sind.
Benötigen Sie eine Dokumentation nicht mehr, löschen Sie die Dokumentation.
- Prüfen Sie, ob die Dokumentation in anderen Dokumentationen verlinkt ist:
a) Verwenden die Schaltfläche Verweisende Dokumentationen anzeigen und entfernen Sie die dortigen Verlinkungen oder ersetzen Sie sie durch neuere Links. - Klicken Sie im Dokumentationseditor auf Ordner der Dokumentation anzeigen.
- Klicken Sie mit der rechten Maustaste auf die Dokumentation (HTML-Dokument).
- Wählen Sie im Kontextmenü Löschen.