Chapter 45. Writing Documentation

This chapter is intended for developers who write documentation. There are no special prerequisites. Part one describes how a chapter should be structured. Part two discusses how domains and connectors should be document. Part three describes how Docbook is used at OpenEngSB.

45.1. General Documentation Guidelines

A chapter should consist of these parts:

Introduction

It should explained who the target audience for this chapter is and in what case this chapter should be read. There should also be a basic summary of what this chapter is about.

Prerequisites

Any prerequisites should be listed. Link to the appropriate chapter or to a website to give the reader a good starting point in case they need to learn something else first.

Context

In the context section the reader should learn in which context this chapter is applicable. If necessary abbrevations and acronyms used in this chapter can be explained here.

Content

The actual content of this chapter. This should be structured in as many sections as appropriate.

Example

If possible there should be an example to illustrate the points of the chapter.

Common Problems

If there are some known pitfalls or bugs they should be described in this section.

Closing Remarks

In this section the content of the chapter can be summarized once more. The reader should get information on what to do next.

It is not necessary that every part is a docbook section. Parts can be combined if it seems appropriate.

45.2. Document a domain or connector

45.2.1. Domain

Each domain gets their own directory in the user guide at domains/<the-domain-name>. The domain-specific documentation should be put in a file named domain.xml. The directory will be used to document connectors for the domain.

The documentation of a domain should at least consist of the following parts:

Description

Describe briefly what the purpose of the Domain is.

Functional interface

The link to the actual java interface (and any domain models used in the interface) at Github. The domain interface and models should have enough Javadoc to explain the usage.

Events

If the domain adds new events to the OpenEngSB, the link to the events package at Github should be provided. The meaning of each events should be documented through the Javadoc at the actual class.

45.2.2. Connector

A connector for a specific domain should be documented in the domain-specific directory. Add a new file with the unique name of the connector.

The documentation of a connector should at least conisst of the following parts:

Description

Provide a description of the external tool and its purpose.

External tool configuration

A section on how to configure the actual external tool for usage with the OpenEngSB has to be provided.

Support for domain interface

Any deviation to the provided functionality of the domain should be documented. E.g a connector may only implement parts of the domain interface.

45.3. Using Docbook

This is not a DocBook manual but rather an explanation what type of docbook tags are used in this documentation. If you are new to DocBook you should read DocBook 5: The Definitive Guide.

45.3.1. Tags

DocBook has many tags to choose from. This list describes which tags should be used in which cases.

Tag Description Example
<command> Used for executables Type <command>ls</command> to get the contents of the directory.
<envar> Used for environment variables PATH
<emphasis> Used to emphasize words in a sentence This chapter explains only the very basics of Git.
<filename> Used for files and directories You can set environment variables in <filename>~/.profile</filename>.
<guibutton> Used to describe buttons in a GUI Press <guibutton>Next</guibutton> to continue with the process.
<guilabel> Used to describe labels in a GUI Select <guilabel>Copy projects into workspace</guilabel>
<guimenu> Used to describe menus in a GUI Go to <guimenu>File</guimenu>, <guimenu>Import...</guimenu>.
<itemizedlist> Used for bullet type lists <itemizedlist><listitem>One</listitem><listitem>Two</listitem></itemizedlist>
<listitem> Used for entries in a list <itemizedlist><listitem>One</listitem><listitem>Two</listitem></itemizedlist>
<option> Used for options of commands <command>mvn</command> <option>clean</option> is used to clean the project.
<orderedlist> Used for numbered lists <orderedlist><listitem>One</listitem><listitem>Two</listitem></orderedlist>
<para> Used for paragraphs <para>This is a paragraph.</para>
<programlisting> Used to display code (e.g. XML or Java). Generally it is a good idea to wrap the contents of this tag in a CDATA section. <programlisting><![CDATA[System.out.println("Hello, world!");]]<</programlisting>
<replaceable> Used for placeholders in examples Type <command> <replaceable>/path/to/maven</replaceable>
<link> Used for links to external resources You should read <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook 5: The Definitive Guide</link>.
<xref> Used for internal links This inserts a link to the description of the the OpenEngSB <xref linkend="architecture" />.
<userinput> Used for data which is entered by the user Type <userinput>n</userinput> to overwrite the default values.
<warning> Used for warnings about a chapter <warning><para>This chapter is out of date.</para></warning>

45.3.1.1. Including an image

Images can be included in this way:

<mediaobject>
  <imageobject>
    <imagedata id="new" fileref="graphics/testclient_message.png"
      format="png" width="400" align="center" />
    </imageobject>
  <caption>Messaging</caption>
</mediaobject>

45.3.1.2. Using a table

There are two types of tables. Normal tables (<table>) and informal tables (<informaltable>)which don't have a caption. Using informal tables should be fine most of the time. Example:

<informaltable>
  <colgroup>
    <col width="50" />
    <col width="100" />
  </colgroup>
  <thead>
    <tr> 
      <td>
        Name
      </td>
      <td>
        Description
      </td>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>
        table
      </td>
      <td>
        A table with a caption
      </td>
    </tr>
    <tr>
      <td>
        informaltable
      </td>
      <td>
        A table without a caption
      </td>
    </tr>
  </tbody>
</informaltable>

45.3.1.3. Generating the documentation

To build the documentation maven with some plugins is used. The full documentation can be generated in one simple step:

cd docs
mvn clean install -Pdocs
        

The documentation can be found in docs/target/docbkx in HTML and PDF format.