Anleitung - Dokumentation schreiben - Rubinius
Author: Less Than Three. <3. http://less.thanthree.com
Description: Rubinius is an implementation of the Ruby programming language. The Rubinius bytecode virtual machine is written in C++. The bytecode compiler is written in pure Ruby. The vast majority of the core library is also written in Ruby, with some supporting primitives that interact with the VM directly.

1.2.3

## Anleitung - Dokumentation schreiben

Die Dokumentation für Rubinius ist integriert mit der Website und dem Blog. Sie nutzt genau wie die übrigen Komponenten Jekyll.

Um zu starten, stelle sicher, dass du die `kramdown` und `jekyll` Gems installiert hast.

    rbx gem install jekyll kramdown

Die Dokumentationsquellen befinden sich im `web/doc` Verzeichnis. Es existieren dort Unterverzeichnisse für alle Sprachen, die bereits in einer Übersetzung vorliegen (wie z.B. diese deutschen Übersetzung).

Jede Übersetzung besitzt ein Inhaltsverzeichnis (z.B. `/web/doc/en/index.markdown`). Der Rest der Dokumentation besteht aus einzelnen Dateien, die YAML Attribute benutzen, um anzugeben, wie die Dokumente zueinander in Beziehung stehen. Im Prinzip kann man die Dokumentation als eine doppelt verkettete Liste von Dokumenten verstehen, bei der jedes Dokument auf ein Vorgänger- sowie einen Nachfolgedokument verweist. Das Inhaltsverzeichnis zeigt dabei die komplette Struktur aller übrigen Dokumente an.

Die YAML Attribute in einem Dokument sehen in etwa wie folgt aus:

    ---
    layout: doc_en
    title: How-To - Write Documentation
    previous: Write a Blog Post
    previous_url: how-to/write-a-blog-post
    next: Translate Documentation
    next_url: how-to/translate-documentation
    ---

Das layout gibt an, welches Jekyll Layout bei der Formatierung des Dokuments genutzt werden soll. Das layout sollte `doc_LANG` entsprechen, wobei LANG ein ISO-639-1 Code für die Sprache ist (z.B. de, en, pl, es etc.).

Das title gibt den Dokumententitel an, der am oberen Rand der Seite dargestellt wird.

Die previous und previous_url Attribute stellen den Titel sowie Link zum vorherigen Dokument dar. Gleichermaßen entsprechen die next und next_url Attribute dem Titel und Link zum folgenden Dokument. Diese werden benutzt, um das Lesen und Durchstöbern der Dokumentation zu vereinfachen und den Arbeitsaufwand beim Neuordnen von Dokumentationsabschnitten zu minimieren.

### Vorhandene Dokumentation bearbeiten

Ein anfänglicher Entwurf für die Dokumentation wurde bereits erstellt. Es gibt aber noch viele Themen, die einer vertiefenden Dokumentation bedürfen.

Um Dokumentation für ein bestehendes Thema hinzuzufügen oder vorhandene Dokumentation zu verbessern, öffne die Datei für das jeweilige Thema unter `web/doc/LANG` und füge dort neue Dokumentation hinzu oder überarbeite diese.

### Neue Dokumentation hinzufügen

Um neue Dokumentation für bisher nicht dokumentierte Themen hinzuzufügen:

1. Erstelle eine neue Datei mit der .markdown Dateiendung unter `web/doc/LANG`.
2. Richte die YAML Attribute ein, sodass auf die neue Datei innerhalb der existierenden Dokumente verlinkt wird. Dies erfordert das Bearbeiten der previous and next Attribute der bereits vorhandenen Dateien, um die neue Datei einzufügen. Ebenso muss ein Eintrag in der `index.markdown` gemacht werden.
3. Damit du Veränderungen noch beim Bearbeiten überprüfen kannst, führe folgenden Befehl aus und besuche die vom Server angegebene URL: `rbx -S jekyll --server --auto`
4. Bearbeite die neue Datei mit dem Markdown Syntax.
5. Im `web/` Verzeichnis, führe `rbx -S jekyll` aus.
6. Mach ein Commit für alle Veränderungen im `web/` Verzeichnis.