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.
A chapter should consist of these parts:
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.
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.
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.
The actual content of this chapter. This should be structured in as many sections as appropriate.
If possible there should be an example to illustrate the points of the chapter.
If there are some known pitfalls or bugs they should be described in this section.
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.
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:
Describe briefly what the purpose of the Domain is.
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.
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.
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:
Provide a description of the external tool and its purpose.
A section on how to configure the actual external tool for usage with the OpenEngSB has to be provided.
Any deviation to the provided functionality of the domain should be documented. E.g a connector may only implement parts of the domain interface.
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.
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> |
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>
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>