Author Reference

(1Q20)


This article describes the conventions for writing articles for the eXist-db documentation set. The eXist-db documentation set is (since beginning 2018) based on a subset of the DocBook 5 content model. If you want to contribute an article (please do) it must conform to the standards described here.

General guidelines

Here are some general writing (and tagging) guidelines:

  • Please start of with a short introduction of your article in one or a few paragraphs before diving in. These paragraphs must be placed before the first <sect1>.

    Describe what the article is about and for whom. What is the subject? Is it for total novices, beginners, advanced programming gurus in Java hyperspace? Prevent readers from diving in and find out that it's not for them.

  • Presenting longer listings can best be done by storing these in separate documents and linking them (see Listings). This makes maintenance easier (ever edited a large CDATA section with XML inside?).

    An additional reason is that somewhere in the future we intend to enable running code-examples directly from the documentation app. For this these examples must be in separate documents. So make sure that at least runnable examples are separated from your text.

  • Of course all the normal technical writing guidelines apply: Keep your target group in mind (what do they know and, more importantly, what not), write correct English, use plenty of examples, split the article in sections and sub-sections that make sense, etc.

Patterns to avoid

The following patterns tend to occur again and again in writing documentation. Please try to avoid them…

The examples exaggerated, but that's for illustration purposes, not to offend anyone.

Avoid the difficult and explain the easy

It is very tempting to skip quickly over some hard parts of the documentation and instead describe some of the easy parts in length. For instance:

To configure the xyz extension you have to create an XML configuration file. Here is an example:

(some skimpy example of a complicated configuration file that is supposed to speak for itself
but does not because its too simple)

To work with the user interface open this, click here, enter the password twice, click ok, bla bla bla, going on for multiple paragraphs…

Well, your reader isn't stupid and hasn't seen a GUI for the first time. So telling him/her that a password needs to be entered twice and that ok must be clicked is completely superfluous. Just point your reader to the GUI and maybe to the right menu but that's all. Believe me, they know how to fill in a dialog box.

But they do not know what all these elements and attributes in the configuration file mean. Even if the names speak for themselves, some explanation will be necessary. Best to describe them all, mention defaults, examples, etc.

And yes, that's hard work, both in thinking and writing. But if you want your xyz extension to be used and useful (that's what you wrote it for, right?) its part of the job.

Being overly polite

Sometimes writers try to be very polite to both the reader and, strangely enough, the system. Since the reader wants it clear and you can't offend a system, don't.

Polite version

Straight version

The logfile should appear.

The logfile appears.

You may enter ...

Enter ...

If you wish you can also...

It is also possible to ...

Also: ...

Please navigate to...

Navigate to ...

Using thus instead of therefore

Somehow there seems to be a preference among eXist-db's documentation writers for the word "thus" when "therefore" is meant. Thus is almost always wrong in this kind of prose, so please default to therefore. If you want to know more read on here.

Java isn't always interesting

Some articles that explain stuff about things in the XQuery realm keep rambling on about stuff in Java or in eXist-db's architecture: Servlets that execute, methods that are called, etc.

Yes, because you are a Java programmer its probably interesting to you. But when the intended audience of the article is XQuery programmers, don't bother them with this. And if you really (really!) think it is necessary information for some of them, add it to a separate section at the bottom.

Technical guidelines

More information about DocBook itself can be found on the official DocBook site.

Collection (directory) structure

  • A single article must be stored in a collection on its own, the article-collection. Related assets or other files will be stored in sub-collections of this. This setup ensures that everything belonging to a single article stays together.

  • In the eXist documentation app, the article-collection will become a sub-collection of the data collection. So an article-collection called new-cool-feature will become /db/apps/doc/data/new-cool-feature.

  • The name of the article-collection should be the same as the document-name of the article itself. So if your article is called new-cool-feature.xml, store it as new-cool-feature/new-cool-feature.xml.

  • Any binary assets (images, etc.) referenced by your article must be stored in a sub-collection assets. So in our example in new-cool-feature/assets.

  • Any non-binary assets (usually included program/text listings) referenced by your article must be stored in a sub-collection listings. So in our example in new-cool-feature/listings.

All rules regarding collection names are not there for technical reasons but to promote consistency. If you deviate and make sure all references are correct it will still work. However, to keep things maintainable it is strongly recommended to follow the rules stated above (or, if you really think they're stupid, apply for a rule change).

Overall XML structure

Here is an example how an article for this documentation set looks like:

<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
  <info>
    <title>
      Document title
    </title>
    <date>
      1Q18
    </date>
    <keywordset>
      <keyword>
        blah
      </keyword>
    </keywordset>
  </info>
  <para>
    Introductory paragraph(s)
  </para>
  <sect1 xml:id="main-id">
    <title>
      Title of first main section
    </title>
    <para>
      Lorem ipsum...
    </para>
    <sect2 xml:id="sub-id">
      <title>
        Title of first sub-section
      </title>
      <para>
        Lorem ipsum...
      </para>
    </sect2>
  </sect1>
  <sect1 xml:id="next-id">
    <title>
      Title of second main section
    </title>
    <para>
      Lorem ipsum...
    </para>
  </sect1>
</article>

Both the processing instructions at the top are optional but strongly recommended. They're present to guide tools like oXygen in validating the document and provide authoring hints.

Article information

Here is an example the article's mandatory information section:

<info>
  <title>
    Author Reference
  </title>
  <date>
    January 2018
  </date>
  <keywordset>
    <keyword>
      authoring
    </keyword>
  </keywordset>
</info>

The following rules and guidelines apply:

  • There must be a title present in a <title> element. This is the main title of the document. It will be displayed at the top of the page.

  • Optional but strongly recommended is a date in the <date> element. This will be displayed below the title and provide the reader with some clue on how old this information is. We all know that sometimes articles get outdated but are not removed... You don't have to provide an exact date. Just month and year will do, or some indication like 1Q18.

  • We use keywords to mark an article for certain subject areas. See Keyword usage.

  • You can add more information in <info> to your heart's desire but the renderer won't use nor display it.

Keyword usage

The <info> element must contain at least one keyword. This is used to create an index on subject. Multiple keywords can be specified by repeating the <keyword> element.

Keywords are always written lower-case and must not contain spaces.

The following keywords are in use:

Keyword

Meaning

application-development

Information related to using eXIst-db as an application platform.

exist

Anything related to eXist-db itself, like legal statements, how to send in bugs, etc.

getting-started

Basic information on how to get eXist-db up and running.

java-development

Information about programming Java for or in eXist-db.

indexing

Information related to eXist-db's indexes.

installation

Information about installing eXist-db

interfaces

Information about specific interfaces eXist-db provides

operations

How to keep eXist-db up and running, not from a programmer's but from a system maintenance point of view.

testing

Information related to testing eXist-db or its applications.

xquery

Information related to XQuery (or XPath) in general or eXist-db's specific features of the language.

Warning:

Tables like the one above tend to get outdated sooner or later (because somebody adds/deletes a keyword and forgets to update it). To see all the keywords actually in use, look at the index-by-subject section of the main documentation page.

Watch out: For legibility reasons the keywords there are presented capitalized. Remember that in the article documents the keywords must be stated in lower-case!

Supported block elements

The following DocBook 5 block level elements are supported for the eXist-db documentation set. Unsupported elements will be flagged when the content is rendered (you'll see a bold red error message in the middle of your story).

Paragraphs

Use <para> to tag text as a paragraph.

Section levels

You can use <sect1> up to <sect3> as section levels. Only <sect1> and <sect2> will appear in the table of contents. Markup in titles is ignored.

Lists

You can use either <itemizedlist> (with bullets) or <orderedlist> (with numbers).

Variable list

A <variablelist> is a bit of a misnomer. It creates lists like this one (the list of block elements you're looking at now), so it's useful for much more than variables.

Notes

Note: About notes

The <note> element creates a noticeable layout like this. The title is optional.

Warnings

Warning:

Both the <warning> and <important> element produce a layout like this. The only difference is the text of the header. You can optionally add a title.

Examples

The <example> element produces an example in a layout like this. It must have a <title> element, which is displayed at the bottom:

An example of an example
Listings

Anything you want to present as a program listing or other fixed text (e.g. a sequence of commands) must be enclosed in a <programlisting> element. There are two ways to provide the actual contents of the listing:

  • Simply enclose the text in the <programlisting> element. Use CDATA if necessary. Any markup will be ignored.

  • Add an xlink:href attribute (xmlns:xlink="http://www.w3.org/1999/xlink") with a reference to a file containing the text. This must be a relative reference (e.g. xlink:href="listings/mylisting.txt"). The contents of the element will be ignored.

    Using the xlink:href attribute is definitely not the proper way to do this. It should be done by using an <xi:include> element inside <programlisting>. However, current XInclude limitations in eXist prevent this from working properly (it can only include XML, not text). So therefore this workaround.

Listings have two display modes:

  • If it's a listing in some language (like XML), add a language attribute with the name of the language. The render will try to add some color coding (if it recognizes it). Here is a listing with language="xml":

    <example-xml example="true">
      <!-- Comment -->
      <p>
        Some text...
      </p>
    </example-xml>
  • For a straight listing, don't add a language attribute. Here is the same listing as above without:

    <example-xml example="true">
      <!-- Comment -->
      <p>
        Some text...
      </p>
    </example-xml>
Figures

Use <figure> or <informalfigure> to add an asset. The effect of both elements is almost the same, the only difference is that an informal figure has no title. DocBook prescribes an elaborate XML construction, here is an example:

<figure>
  <title>
    Figure title here
  </title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="assets/powered-by-exist.gif" width="50%"/>
    </imageobject>
  </mediaobject>
</figure>

This produces:

Figure title here
Figure title here

The width attribute is the only size-related attribute used. It sets the width relative to the available horizontal space. If you don't specify a width a default of 75% is used.

Tables

Use <table> or <informaltable> to add a table. The effect of both elements is almost the same, the only difference is that an informal table has no title. Table layout is kept simple and straight. Here is how a simple table looks like:

<table>
  <title>
    Table title
  </title>
  <tgroup cols="2">
    <colspec colwidth="30%"/>
    <colspec/>
    <thead>
      <row>
        <entry>
          Col 1
        </entry>
        <entry>
          Col 2
        </entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>
          <para>
            Bla
          </para>
        </entry>
        <entry>
          <para>
            More bla
          </para>
        </entry>
      </row>
      <row>
        <entry>
          <para>
            Blegh
          </para>
        </entry>
        <entry>
          <para>
            More blegh
          </para>
        </entry>
      </row>
    </tbody>
  </tgroup>
</table>

And this is the result:

Col 1

Col 2

Bla

More bla

Blegh

More blegh

Supported inline elements

The following inline elements are supported:

Warning:

Inline elements in <title> elements are not supported. Any markup in titles is ignored.

Emphasis

Use <emphasis> for emphasizing.

Although discouraged, you can request a specific emphasis type:

  • Use role="bold" for bold emphasis.

  • Use role="underline" for underlined emphasis.

  • Use role="italic" for italic emphasis. This looks the same as no role attribute but produces an <i> instead of an <em>.

GUI Items

Use <guimenuitem> around anything referring to choices in a GUI, for instance menu choices. The effect is now simple italic but that might change later.

Code

Use <code> or <literal> for literals, pieces of code, commands, etc. The result will be mono-spaced.

The general guideline is to use this for everything that lists pieces of code, attributes, variable names, etc. For elements use <tag>.

Tags

A <tag> element surrounds its content with < and > and formats it like code. Meant to make life easier: <tag>xxx</tag> is the shorter version of <code><xxx></code>.

Figures

Use the <inlinemediaobject> to add an asset inline in the text. DocBook prescribes an elaborate XML construction, here is an example of a paragraph with an inline figure:

<para>
  There is an asset
  <inlinemediaobject>
    <imageobject>
      <imagedata fileref="assets/webstart.small.jpg"/>
    </imageobject>
  </inlinemediaobject>
  here.
</para>

This produces:

There is an asset here.

The width attribute is the only size-related attribute recognized and used.

Internal links

You can create a link to any block level element with the <xref> element. To do so, give the target an identifier by using xml:id="..." and mention this identifier in the linkend attribute of the <xref>.

You can generate a specific link text by adding an xreflabel attribute to the target element, like here: directory structure list. If this attribute is not present on the target its title is used, like this: General guidelines. If there is no title, the name of the element is presented.

External links

Links to external sources are done with the <link> element. Place the target's full URI in the xlink:href attribute. For instance, <link xlink:href="https://exist-db.org/exist/apps/homepage/index.html"> links to the eXist home page.

To open the link on a new page, add condition="_blank".

Article links

To create a link to another article in this documentation set, also use the <link> element. However, use the target's document name (without the .xml extension) as the link address. For instance, <link xlink:href="documentation"> links to the documentation home page.

Generating indexes

Indexes can be automagicly generated. For examples have a look at the documentation home page. There are three variations:

Alphabetical index on title

Add a role="indexontitle" attribute to a <para> element. An index on title will be generated after it.

Index on keyword, all

Add a role="indexonkeyword" attribute to a <para> element. An index on keywords (as specified in the <info> element, see Keyword usage) will be generated after it.

Index on keyword, single

Add a role="indexonkeyword:somekeyword" attribute to a <para> element to generate a list of articles with this specific keyword (as specified in the <info> element, see Keyword usage).

Additional tools

There are two additional pages in the documentation app to help authors and editors:

Editorial view

The editorial view provides an overview of all the articles and their incoming and outgoing links.

Diagnostics

Performs limited diagnostics. Checks whether the outgoing links in articles to other articles, listings and assets are ok. Also checks whether there are unreferenced (and therefore superfluous) listings and assets.