Dokumentationen erstellen

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.

1. 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:

1. Wenn Sie einen Anzeigenamen unter Verlinkte Dokumentationen auf dieser Seite des Dokumentationseditors vergeben haben, verwendet das System diesen Namen.
2. 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.
3. 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.

 

Eine Vorlagenkategorie anlegen

Aktion	Beschreibung
Neu > Dokumentation - Vorlagenkategorie	Legt innerhalb einer Vorlage eine neue Kategorie an.

 

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. Um die Aktion zu wählen, markieren Sie den Ordner Medien. Wenn Medien bereits in einem anderen Medienordner unterhalb einer Vorlage vorhanden sind, werden diese nur verlinkt. Dasselbe gilt, wenn sich ein Bild oder Video außerhalb des Dokumentationsbereiches befindet. Dieses verlinkt das System nur 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. Der Name hat bei der Suche in der Ergebnisliste die höchste Relevanz. Treffer, die das System im Namen der Dokumentation findet, zeigt das gefundene Dokument an erster Stelle im Suchergebnis an. Das System fügt automatisch die Endung .html an die Dokumentation an, sobald Sie die Dokumentation speichern.
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 H1 H2 H3 H3 H3 H2 H2 H3 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. Beispiel H1 H2 H1  (die zweite H1 wird wie eine H2 eingerückt) H2 H3
Neue Übersicht ab hier erstellen (nachts)	Erzeugt automatisch jede Nacht ab dieser Dokumentation eine neue Übersichtsdokumentation. Eine Übersichtsdokumentation besitzt eine eigene Baumstruktur. Das ist etwa sinnvoll, wenn Sie eine Dokumentation an Kollegen weitergeben möchten und die Kollegen in der Baumstruktur nur diese Dokumentation und weitere dazugehörige Dokumentationen sehen können sollen. Sie können die Übersicht auch manuell generieren.
Beschreibung	Definiert eine Beschreibung für die Dokumentation. Die Beschreibung hat eine hohe Relevanz im Suchergebnis. Treffer in der Beschreibung werden gleich nach den Treffern im Namen der Dokumentation bewertet. Verwenden Sie dieses Feld, um etwa Schreibfehler abzufangen, etwa Plugin und Plug-in. Wenn die Dokumentation das Wort Plug-in enthält, findet ein Benutzer sie unter dem Begriff Plugin nicht. Tragen Sie dieses Wort in das Feld Beschreibung ein, stellt das System diese Dokumentation ebenfalls im Suchergebnis als Treffer dar.
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. Der Bereich können Sie nach dem Speichern nicht mehr ändern. Um eine Dokumentation dennoch zu verschieben, können Sie diese über die Ordnerstruktur der Dokumentation verschieben. Besser ist es allerdings, mit Vorlagen zu arbeiten und diese zu verschieben. Den Ablageort können Sie auch nachträglich ändern. Das System verschiebt die Dokumentation dorthin.

Übersicht manuell generieren

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. Solange Sie auf dieser Arbeitskopie arbeiten, bleibt die aktuelle Dokumentation auf dem Stand, wie sie ist. Das System veröffentlicht Ihre Änderungen nicht. Pro Dokumentation existiert nur einmal der Typ Arbeitskopie.
Historie	Vergangene Versionen der Dokumentation. Beliebig viele Einträge mit dem Typ Historie können in einer Dokumentation vorkommen.

Der HTML-Editor

---

Im HTML-Editor erstellen Sie den Inhalt Ihrer Dokumentation. Sie fügen dort Ihren Text ein oder formatieren ihn.

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

---

Benötigen Sie eine Dokumentation nicht mehr, löschen Sie die Dokumentation.

1. 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.
2. Klicken Sie im Dokumentationseditor auf Ordner der Dokumentation anzeigen.
3. Klicken Sie mit der rechten Maustaste auf die Dokumentation (HTML-Dokument).
4. Wählen Sie im Kontextmenü Löschen.