For writing documentation we use Docbook, but not all tags, here are few info about some common mistakes or some limitations once it's being built

programlisting

For each section of XML, JAVA, HTML, one should use the <programlisting/> tag that way:

<programlisting role="XML"><![CDATA[<test>

  <foo/>

</test>]]></programlisting>

JHighlight is used to create syntax coloration on the piece of code, looking at the 'role' attribute.

One can use "XML", "JAVA", "Groovy", "HTML" or "XHTML" as 'role'.

Several things to keep in mind with this attribute:

• spacing is important, it will be displayed as-is so watch out the left space padding and the auto-formatter tools
• lines shouldn't be longer than 80 characters, split your lines in advance
  
• 2 spaces is a good indentation to use
• programlisting shouldn't be used within a <para/> or the output through JHighlight will be garbage.

programlistingco

To use callouts bullets here is an example:

<programlistingco>
  <areaspec>
     <area id="test.example.thing.1" coords='1' />
     <area id="test.example.thing.2" coords='4' />
     <area id="test.example.thing.3" coords='5' />
  </areaspec>
  <programlisting role="XML"><![CDATA[My Line 1
This is Line 2
My Third Line
This is Line 4
Final line]]></programlisting>
  <calloutlist>
    <callout arearefs="test.example.thing.1">
      <para>Blabla about Line 1</para>
    </callout
    <callout arearefs="test.example.thing.2">
      <para>Blabla about Line 4</para>
    </callout
    <callout arearefs="test.example.thing.3">
      <para>Blabla about Line 5</para>
    </callout>
  </calloutlist>
</programlistingco>

section

Please use 'section' (Not sect1, sect2...), don't forget a 'title', most sections will look like:

     <section>

        <title>My Title</title>

        <para></para>

     </section

listitem

You can't just use <listitem>blah</listitem> it must have a tag inside such as: <listitem><para>blah</para></listitem>