Home
The DITA documentation process
File and folder naming conventions
Using an organisation-wide, well-documented file naming and folder structure convention will improve the usability of the authoring process for DITA authors, especially those working in a team.
File and folder structure
When working with a file, you should create a folder structure that makes it easy for authors to locate topics to edit or cross-reference.

Introduction
Information types and topics
Topics are the building blocks of modular documents, and organising topics by semantic information types is one of the architectural features of DITA.
DITA map files
Syntax and mark-up
Language and punctuation
Graphics and figures
Cross-referencing
Cross-references are a means of binding individual topics into a coherent and navigable document.
Content re-use
Metadata, conditional processing, and indexing
The DITA documentation process
- Structured authoring documentation stages
  The documentation process within a DITA workflow can be separated into stages of building, associating, and publishing.
- Unit testing in a team
  A process where multiple authors are working on a large repository of topics can make it difficult to manage the quality and consistency of the content. Unit testing is a technique to identify validation errors earlier in the documentation process.
- Restricting authors and limiting element choices
  To make it easier for authors to choose semantic mark-up elements, it is possible to reduce the number of elements available for selection. This restriction can be managed by an authoring tool, or through the constraints mechanism introduced in DITA 1.2.
- File and folder naming conventions
  Using an organisation-wide, well-documented file naming and folder structure convention will improve the usability of the authoring process for DITA authors, especially those working in a team.
  - File and folder structure
    When working with a file, you should create a folder structure that makes it easy for authors to locate topics to edit or cross-reference.
  - File names
    Having predictable, consistent file names makes it easier for DITA authors to locate topic and other files in a repository.
  - Case-sensitive file and folder names
    When working in a DITA environment, files and folders must be treated as case-sensitive, and all members of the team must adhere to agreed file naming conventions.
  - Avoiding special characters in file names
    Special characters must not be used in file names.
  - File extensions for DITA topics and ditamaps
    The .dita file extension should be used for DITA topics, and the .ditamap extension for ditamaps.
  - Specialised element and attribute naming convention
    Specialised elements and attributes should be named using CamelCase with the first character in lower case.
- Elements for pre-publish review
  The draft-comment element allows review and discussion information to be embedded within topic mark-up. The more basic XML comment can also be used for a similar purpose.
- The DITA publishing process
  XSL-T and XSL-FO are the technologies that underpin most DITA publishing tools.
- Page numbering in page layout documents
  A single page number sequence through an entire page layout document generated from DITA is often preferable to the traditional system of different page number sequences for front matter and back matter.
- Content Management Systems
  Although it is possible to create, manage and edit content in DITA without a CMS, it is invariably easier with the aid of a CMS.
DITA authoring concepts
Moving from style-based authoring to a structured authoring methodology such as DITA requires a radically different approach to writing.

File and folder structure

When working with a file, you should create a folder structure that makes it easy for authors to locate topics to edit or cross-reference.

The ideal file structure for a DITA project is to have ditamaps at the root level of the documentation repository folder, and content topics stored in sub-folders down from the root. This structure ensures that topicref links to content always move down the tree structure. As ditamaps are an informational superset of topics, having ditamaps in a superfolder is a logical approach.

Images and other media resources should be stored in a separate folder (eg, /images).

There are a number of file topologies that you can use, including:

by information type (eg, concept, task, reference)
by system component documented (eg, engine, fuel system)
by subject area (eg, Getting Started, Working with Debits).

Using a logical, context-free storage location for topics reduces the problems associated with having to later move files from one project folder to another project folder. It also makes the files easier to find.

Never base storage locations on where you want to output files to be generated, as this introduces context into file locations, and breaks the fundamental principle of separation of content from format from delivery.

Avoid using a flat or shallow file structure, with hundreds of topic files stored in one folder. This structure may result in slower file retrieval in DITA editors, where the File Open dialog, for instance, needs to list all the files for selection.