1.2.3

## How-To - Write Documentation

The Rubinius documentation is integrated with the website and blog. It uses Jekyll just like the other components.

To get started, ensure you have the `kramdown` and `jekyll` gems installed.

    rbx gem install jekyll kramdown

The documentation source is under the `web/doc` directory. There are subdirectories for each language to which the documentation has been translated (eg `en`, `es`, etc.).

There is a Table of Contents for each translation (e.g. `/web/doc/pt-br/index.markdown`). The rest of the documentation consists of single files that have YAML attributes to specify how the documents are connected. Essentially, the documentation can be viewed as a doubly-linked list of documents with each document pointing to the previous and next document. The Table of Contents document shows the complete structure.

The YAML attributes in a document look like the following:

    ---
    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
    ---

The layout specifies which Jekyll layout to use when formatting the document. The layout should be `doc_LANG`, where LANG is the ISO-639-2 code for the language.

The title specifies the document title that is displayed at the top of the page.

The previous and previous_url attributes give the title and link to the previous document. Likewise, the next and next_url attributes give the title and link for the next document. These are used to enhance browsing the documentation and limiting the amount of work necessary to re-order parts of the documentation.

Both the source for the documentation and the files generated by Jekyll are committed to the Rubinius repository. When people clone the source repository, they can run `rake docs` to view the documentation before they have built Rubinius or if having problems building Rubinius.

### Editing Existing Documentation

An initial outline for the documentation has been created. There are many topics that merely need to have documentation written for them.

To add documentation for an existing topic or to fix existing documentation:

1. Open the file for the topic under `web/doc/LANG`.
2. Add or improve the documentation.
3. To view your updates while you are working on them, run `rbx -S jekyll --server --auto` in the `web/` directory.
4. Once finished adding or editing documentation, commit your changes to the source files.
5. Run `rbx -S jekyll` in the `web/` directory to force update of all generated files in `web/_site`.
6. Commit the generated files. If making a small change, the generated files can be committed with the documentation source files. If making many changes, commit the generated files separately to make reviewing changes more simple.

### Adding New Documentation

To add documentation for which no existing topic exists:

1. Create a new file with the .markdown extension under `web/doc/LANG`.
2. Set up the attributes to link the new file into the existing files. This will require editing the previous and next attributes of the existing files to insert the new file, as well as adding an entry to `index.markdown`.
3. To view your updates while you are working on them, run `rbx -S jekyll --server --auto`
4. Edit the new file using Markdown syntax.
5. Once finished adding or editing documentation, commit your changes to the source files.
6. Run `rbx -S jekyll` in the `web/` directory to force update of all generated files in `web/_site`.
7. Commit the generated files. If making a small change, the generated files can be committed with the documentation source files. If making many changes, commit the generated files separately to make reviewing changes more simple.