<!DOCTYPE html>
<html>
<head>
<title>dita-project-best-practices</title>
</head>
<body>
<h1>dita-project-best-practices</h1>
<p>A small DITA project skeleton exemplifying best practices to reuse content and to manage
links. The project favors using DITA 1.2 keyref indirect links over direct DITA 1.1
links.</p>
<p>If you want to start a DITA project from zero, obeying such a structure may help you
in:</p>
<ol>
<li>Growing the project in a healthy sustainable way.</li>
<li>Give you a good overview over what you are reusing.</li>
<li>Allow easier link management.</li>
</ol>
<p>Let's try to take a look at the resources which comprise this project:</p>
<ul>
<li>"talking-circle.ditamap" - The main project DITA Map. In our case it's a small
example DITA Map discussing about an hypothetical software application.</li>
<li>"filters" - This folder contains all DITAVAL filter files which are used to obtain
various outputs from the project contents.</li>
<li>"images" - This folder contains all image files used in the project. You can add
various subfolders to it.</li>
<li>"links" - This folder contains various link-related mappings: <ul>
<li>"externalLinks.ditamap" - Contains key definitions for all your external
links, usually links to external web resources.</li>
<li>"internalLinks.ditamap" - Contains key definitions for the project's topics
referenced from other topics.</li>
<li>"relationshipTable.ditamap" - Contains the relationship table describing
links between various topics.</li>
</ul>
</li>
<li>"reuse" - This folder contains mappings for reused content: <ul>
<li>"reusableComponents.dita" - This topic contains a list of reusable elements.
For each element there is a description which instructs the technical writer
how to reuse it. In a larger project there are probably more than one such
topics.</li>
<li>"reusableImageReferences.ditamap" - Maps keys for each used image.</li>
<li>"reusableProductNames.ditamap" - Defines small pieces of text which can be
reused using keyref.</li>
<li>"reusables.ditamap" - Binds together all these resources, assigns a key for
the reusable components topic.</li>
</ul>
</li>
<li>"tasks, topics, concepts, references, etc" - Folders which contain the actual DITA
content, either split in subfolders by topic type or by some other project-specific
role.</li>
</ul>
</body>
</html>