Vorlage für Dokumentationen

Einleitung

Die folgenden Empfehlungen sollen Ihnen beim Erstellen von Dokumentationen die Arbeit erleichtern. Es handelt sich nicht um eine strenge Vorgabe, sie dient als Leitfaden, damit die Dokumentationen möglichst einheitlich aufgebaut und so für die Nutzer der Dokumentationsseite einfach zu lesen sind.

Das Grundgerüst

Zunächst legen Sie eine neue Seite an. Dazu gehen Sie wie folgt vor:

Anmelden

  • Sie klicken auf „Neue Seite erstellen“:

Neue Seite erstellen

  • Sie geben der neuen Seite einen Namen. Normalerweise müssen Sie für eine neue Seite keinen neuen Namensraum erstellen, wenn diese keine Unterseiten hat. Sie können den Haken im folgenden Dialog also i.d.R. entfernen:

Neue Seite: Namen eingeben

Sie haben damit eine neue Seite erstellt. Das Grundgerüst einer Dokumentation ist dann sehr einfach:

====== Hauptüberschrift (Titel der Dokumentation) ======

===== Einleitung =====

In dieser Dokumentation wird erklärt, wie....

===== Unterüberschrift =====

...

===== Unterüberschrift =====

==== Unterunterüberschrift ====

...

Das obige Gerüst kann per Cut'n'Paste einfach übernommen werden.

Tips & Tricks

Eine Anleitung im DokuWiki-Format zu schreiben, ist extrem einfach. Hier ein paar Tips & Tricks:

  • Bei Fragen zur Formatierung können Sie einfach die Syntax-Seite für DokuWiki aufrufen. Die Syntax ist so einfach, dass Sie vermutlich sofort intuitiv die meisten Formatierungen beherrschen.
  • Wenn Sie Screenshots von Programmfenstern anfertigen wollen, die hauptsächlich Text oder Linien enthalten, sollten Sie beim Abspeichern einen Dateityp wie „.gif“ oder „.png“ wählen, weil „.jpg“ dafür optimiert ist, Bilder wie z.B. eine Landschaftsaufnahme zu speichern. Texte werden durch das Speichern in „.jpg“ schlechter lesbar.
  • Schauen Sie sich ruhig bei Seiten im RZ-Dokumentations-Wiki, die Ihnen gefallen, die Syntax an, in dem Sie sich den Quelltext ansehen. Dies geschieht durch Klick auf „Zeige Quelltext“:

Zeige Quelltext

  • Hier ein paar häufig verwendete Elemente, die Sie in den durch RZ- und IT-Cluster-Mitarbeitern erstellten Seiten immer wieder finden:
    • Fett-, Kursivdruck, Code-Text, Unterstreichen und Durchstreichen finden Sie als Icons im Wiki-Editor. Die Wiki-Befehle für diese Schrifteigenschaften werden dann im Klartext in Ihrer Wiki-Seite eingetragen, Sie könne sie auch direkt im laufenden Text ohne Umweg über die Icons tippen.
    • Wir setzen gerne für Hinweise/Warnungen etc. Notizkästen ein:
      <note>
      Ich bin ein Hinweis.
      </note>
      
      <note important>
      Ich bin ein wichtiger Hinweis!
      </note>
      
      <note warning>
      Ich bin eine Warnung.
      </note>
      
      <note tip>
      Ich bin ein Tip.
      </note>

      Das Ganze sieht dann so aus:

Ich bin ein Hinweis.
Ich bin ein wichtiger Hinweis!
Ich bin eine Warnung.
Ich bin ein Tip.
  • Fußnoten werden wie folgt gemacht:
    Hier soll eine Fußnote dran.((Ich bin die dazugehörige Fußnote.))

    Das Ergebnis: „Hier soll eine Fußnote dran.1)

  • Tags: Wenn Sie eine Seite schreiben, die spezifisch für ein bestimmtes Betriebssystem (oder sogar mehrere Betriebssysteme) ist, dann sollten Sie diese mit einem passenden Tag versehen, denn das DokuWiki kann auf diese Weise Ihre Seite automatisch unter den Betriebssystemen listen, für die sie erstellt ist. Tags können selbstverständlich auch im Nachinein eingepflegt werden. Wenn Sie beispielsweise eine Anleitung für Linux verfassen, markieren Sie diese mit
    {{tag>Linux}}

    am Ende der Seite. Mehrere Tags werden durch Leerstellen getrennt angegeben:

    {{tag>Windows_XP Windows_7}}

    Es gibt im Moment folgende Tags:

Wir freuen uns auf Ihre Beiträge zum User-Dokumentations-Wiki. Viel Spaß beim Dokumentieren!

Trauen Sie sich einfach. Schreiben Sie die Doku, die Ihrer Meinung nach noch fehlt, die Mitarbeiter des IT-Clusters und des Rechenzentrums stehen Ihnen mit Rat und Tat zur Seite.
1)
Ich bin die dazugehörige Fußnote.
Melden Sie sich an, um einen Kommentar zu erstellen.
user-contrib/vorlage.txt · Zuletzt geändert: 10:56 13. March 2012 von Christian Marg
Valid CSS Driven by DokuWiki Recent changes RSS feed Valid XHTML 1.0