Topic pages

Topic pages contain actual help content that will address tasks the user is trying to finish and problems the user is likely to encounter. Each topic page should contain only one task, concept or reference item. Topic pages should be the absolute smallest amount of information required to accomplish something. Each topic page should be specified with the type="topic" attribute and should (like all pages) be assigned a unique identifier in the id="" attribute that ideally matches the filename of the page.

A topic page also contains a link back to a guide page. If there is no link back to the guide page, the guide page will not list the topic page. This can be useful, because you can spend some time writing the topic page before you add a link to the guide page. Once the topic page is finished, you can add the link to the guide page and the finished topic page will be listed on the guide page.

A topic page could, for instance, contain an introductory paragraph and a list of steps:

<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="planting">

  <info>
    <link type="guide" xref="index"/>
  </info>

  <title>Planting Beans</title>
    <p>By the end of this page, you will be able to plant your magic beans and nurture them into a bean sprout.</p>

  <steps>
    <item>
      <p>Dig a hole 5cm deep.</p>
    </item>
    <item>
      <p>Place your magic beans in the hole.</p>
    </item>
    <item>
      <p>Fill the hole with clean dirt and pat it level.</p>
    </item>
    <item>
      <p>Water daily.</p>
    </item>
  </steps>

</page>

Topic pages should fit on your computer screen. If your topic is very long, you may wish to create a guide page for it and split the long topic page into a number of shorter topic pages. If you find yourself having to use more than two heading depths in a topic page, consider that you may have more than one topic.