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.

General Documentation Guidelines

A chapter should consist of these parts:

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

Document a domain or connector

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:

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:

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.

Tags

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

TagDescriptionExample
<command>Used for executablesType <command>ls</command> to get the contents of the directory.
<envar>Used for environment variables<envar>PATH</envar>
<emphasis> Used to emphasize words in a sentenceThis chapter explains only the <emphasis>very</emphasis> basics of Git.
<filename> Used for files and directoriesYou 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 GUISelect <guilabel>Copy projects into workspace</guilabel>
<guimenu> Used to describe menus in a GUIGo 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>{your code}</programlisting>
<replaceable>Used for placeholders in examplesType <command> <replaceable>/path/to/maven</replaceable>
<link>Used for links to external resourcesYou should read <link xlink:href="http://www.docbook.org/tdg5/en/html/docbook.html">DocBook 5: The Definitive Guide</link>.
<xref>Used for internal linksThis inserts a link to the description of the the OpenEngSB <xref linkend="architecture"/>.
<userinput>Used for data which is entered by the userType <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>