Contributing to the Apache Geode Documentation

Apache Geode welcomes your contributions to the community’s documentation efforts. You can participate by writing new content, reviewing and editing existing content, or fixing bugs. This document covers the following topics:

For instructions on building the documentation locally, see ../geode-book/README.md.

Working with Markdown Files

You can edit markdown files in any text editor. For more, read Daring Fireball’s Markdown Syntax page.

Working with Images and Graphics

Image files in .gif or .png format are in the docs/images directory in the Apache Geode docs repo. Images in .svg format are in the docs/images_svg directory.

Most of the Apache Geode image files have been converted to the open source SVG format. You can insert SVG images directly into an XML topic and modify images using a SVG editor.

The Wikipedia page Comparison of Vector Graphics Editors provides a list and comparison of commercial and free vector graphics editors. Note, however, that not all of these programs support the SVG format.

Writing Guidelines

The most important advice we can provide for working with the Apache Geode docs is to spend some time becoming familiar with the existing source files and the structure of the project directory. In particular, note the following conventions and tips:

Product Name Variables

For flexibility, the product name (a long version and a short one) and version are defined as variables. Here’s how to use them:

Define these three variables in ../geode-book/config.yml:

template_variables:
  - product_name_long: Apache Geode
  - product_name: Geode
  - product_version: 1.2

Use the following Ruby syntax to refer to these variables everywhere except in title: lines:

<%=vars.product_name %>
<%=vars.product_name_long %>
<%=vars.product_version %>

You can’t use these variables in title: lines. Here’s the workaround:

Instead of:

---
title: Apache Geode 1.2 Documentation
---

Do this:

<% set_title(product_name_long, product_version, "Documentation") %>

Why? Because the title: construct is not Ruby code, it’s YAML, and it cannot interpret Ruby variables.

Cautions: