Getting structure into the documentation

Putting our pieces together now, gives us a database for storing the help, an editor (MarkdownPad) for editing, and a converter (Pandoc) for performing conversion and a typesetting system XeTeX.

But there are still a few thing missing, the first thing we need a way to describe the structure of our help. Dynamics NAV is based on “objects” indexed with numbers. The catch is, that there is no “user understandable” logic to the numbering. So we cannot say that the content in the manual should be ordered by object numbers.

We created a XML description of the structure, called structure.xml, it look a bit like this:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<Manual>
  <Info>
    <Title>Demo Documention</Title>
    <Author>E Foqus Documentation 2015 (c)</Author>
    <Preface Type="Article" ID="Introduction" />
  </Info>
  <Chapters>
    <Chapter No="1" Title="The First Chapter">
      <Preface Type="Article" ID="chapter1intro" />
      <Topics>
        <Topic Type="Table" ID="18">
          <SubTopics>
            <SubTopic Type="Table" ID="21" />
          </SubTopics>            
         </Topic>
      </Topics>
    </Chapter>
    <Chapter No="2" Title="A chapter to far..">
      <Preface Type="Article" ID="charpter2intro" />
      <Topics>
        <Topic Type="Table" ID="24" />
      </Topics>
    </Chapter>
  </Chapters>
</Manual>

If you look at the table of content (ToC) in a book, this closly resembles what we have in structure.xml. The other element called <Manual> has a <Info> section with setting for the frontpage and an preface article. Then follows the <Chapters> section with multiple <Chapters>.

Each <Chapter> has a title, a preface article and a series of topics with sub-topics embedded.

Every time we have a preface, a topic or a sub-topic, it can have the following types:

* Article – Points to an article
* Table – Points to a table
* Page – Points to a page
* Report – Points to a report
* XMLport – Points to a XML Port

Each of these can be found in our NAV database.

When we look at the NAV 2015 Help server, we see the collapsible menu on the left, this structure resembles the ToC of a manual, and is stored in a filed called ToC.xml on the server. We can use our structure.xml to fill out the Help Server ToC.xml file.

One thought on “Getting structure into the documentation”

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.