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:

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.