New Documentation System for Project Zero

This page describes the new documentation system for Project Zero that keeps the documentation in SVN with the source code and generates an HTML doc set from that source material

Working Assumptions

• DITA and XHTML are the source file format.
  • We will use XHTML for topics and DITA Maps.
• We will build a custom tool to transform the DITA maps to appropriate TOC pages. The XHTML will also be transformed to include navigation, breadcrumbs and fixed up references.
• The module structure of Zero will show through.
• We can get by without much conditional logic in the docs
• Printing - support printing a single module at a time, rendered as a single HTML file
• Offline browsing - supported through saving the files using browser or exporting as a ZIP
• Google will be used for searching. We should allow someone to search the docs only.

Open Issues

• How do we factor in RESTDoc?

Module Directory Structure

All zero modules (zero.core, zero.data, etc) will contain the following directory structure for docs:

module/docs/<language>/toc.ditamap
module/docs/<language>/overview.html
module/docs/<language>/topic1.html
module/docs/<language>/topic2.html
module/docs/<language>/topic3.html
module/docs/images/*

The toc.ditamap file contains the overview and an ordered list of topics for this module. The topic html files contains the content with a title, keyword and other required tags. The images directory is not contained in the language folder and contains all images used in the topics. If necessary, there can be localized images contained within an images directory beneath the directory. This should only be used if the image needs to be translated. Javadoc (including PHP API doc) will be linked into the TOC.

We will also have a separate SVN module or modules for the following:

• Getting Started
• Overview

Linking will be straightforward. You will either link to something in the current module or another module. To link to another module, the link will begin with a /, e.g., /other_module/topic1.html. To link to a local page, the link will be topic1.html. To include any image which can only be within your module, use a link of the form image/image1.jpg.

Table of Contents (TOC)

There will be a global ditamap that has navrefs that link a module's ditamap.
A module's ditamap will contain topicrefs for the overview and nested topicrefs to the html files as defined above.

Below is an example of a master table of contents in the doctoc module and a table of contents for a module, doc1.

/doctoc/docs/en/toc.ditamap

<?xml version="1.0" encoding="ISO-8859-1"?>
<map id="debugger_top"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://docs.oasis-open.org/dita/v1.0.1/schema/map.xsd">
  <title>Table of Contents Title</title>
  <navref mapref="/doc1/toc.ditamap"/>
  <navref mapref="/doc2/toc.ditamap"/>
</map>

/doc1/docs/en/toc.ditamap

<?xml version="1.0" encoding="ISO-8859-1"?>
<map id="doc1_toc"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://docs.oasis-open.org/dita/v1.0.1/schema/map.xsd">
  <topicref href="overview.html">
    <topicref href="topic2.html" />
    <topicref href="topic3.html" />
  </topicref>        
</map>

Topic

The overview will contain a title, a short description and a body. A topic will also contain a title, a short description (just 1-2 sentence summary of the article so users can quickly decide if it's what they're looking for) and a body. Linking to another topic will either be relative, e.g., topic2.html or /another_module/topic3.html.

Generation

A super-duper ditamap will be generated that contains all the ditamaps merged together based on the global ditamap.
A Table of Contents will be generated from the super ditamap. The short description will be part of the overview for a module
The overview.html will be the contents for the Module.

A page (overview or topic) would have a header, a breadcrumb, the body, and a footer. Either the header or footer would contain navigation. The navigation would allow you to go to the previous or next module or the previous or next topic.

All images will be copied to a module specific images directory. The language specific images will overlay the module images.

The pages will be straight xHTML styled using doc-specific CSS. For a quick reference on xHTML tagging, see this site: http://xhtml.com/en/xhtml/reference/. We will plan for a Javascript plugin on every page to allow for comments.

The DITA documents will be stored in a module as "source". These files will not be packaged during an export, however, even if include source is selected. The output files for each module will be published in higher level constructs such as the the Developers Guide; they will not be put back into SVN. In the future, the module-specific output files may be published within the module's public directory for use in standalone scenarios (for example, catalog).

Published pages are published at "latest" or a version-specific location. Version numbers will be displayed in doc headers to make it easy for users to distinguish between versions.

Templates

A templates for new documents is described and provided in the Article development process document.