This session was presented by Mayur Bhandarkar at the DITA-XML Workshop held at Pune on Saturday, 5 May 2018. During this session Mayur shared his knowledge on how one should plan any DITA-XML project without using any specific Content Management Software.
1. Let’s Start a
Documentation Project
Proprietary & Confidential
INC-1 (Public) A known fact; publicly available information; if compromised, it will have no bearing upon the business
function / gain to another entity / financial loss to organization / loss of organization’s image or market value.
6. 6
The Deliverables - Example
• A product named Widget by Example Corporation is
having its first release.
• The commissioned deliverables are:
– Example Widget Release Notes
– Example Widget Installation Guide
– Example Widget User’s Guide
• The commissioned delivery formats are:
– PDFs (for all guides)
– CHMs (only for User’s Guide)
– HTML Help (one output integrating all guides)
9. 9
The Content Components Description
Content Component Content Type Description
Variables Library Topic A placeholder for names that might change during
the lifecycle of a release, or future releases.
Images Image Media files in formats like JPG, PNG, GIF, etc.
Topics Topic Topics contain all the content and are of three
types: Concepts, Tasks, or References.
Maps Map Maps are placeholders for all the topics part of a
release. Also acts as the TOC of the guide.
Publications Publication Publications contain all components of a
project/guide. It is used for generating multiple
outputs using a single source.
12. 12
The Folder Structure
• The folder structure shows where your product
folder resides within the CMS.
• The folder structure organizes the content
components of the product within the repository.
• The folder structure has to be consistent for all
products in the CMS.
13. 13
The Skeletal Folder Structure
Main
Folder
Product
Suite 01
Product
01-01
Product
01-02
Product
Suite 02
Product
02-01
Product
02-02
14. 14
The Folder Structure - Example
Example
Corp
Micro
Tools
Notes Sketches
Nano
Tools
Gestures Biometrics
15. 15
The Folder Structure – Folder Type
Folder Name Folder Type
Example Corp None
• Micro Tools None
• Notes None
• Sketches None
• Nano Tools None
• Gesture None
• Biometrics None
23. 23
The Folder Structure – Folder Type
Folder Name Folder Type
Widgets None
• Variables Library Topic
• Images Image
• Topics Topic
• Maps Map
• Publications Publication
24. 24
The Folder Structure – Common Folders
Widgets
Front Matter Shared Variables Images Topics Maps Publications
25. 25
The Folder Structure – Folder Type
Folder Name Folder Type
Widgets None
• Front Matter Topic
• Shared Components None
• Variables Library Topic
• Images Image
• Topics Topic
• Maps Map
• Publications Publication
26. 26
The Folder Structure – Common Topics
Widgets
Front Matter
Important
Information
Support Conventions
Related
Documents
Shared Variables Images Topics Maps Publications
27. 27
The Folder Structure – Topic Type
Folder Name Folder Type
Widgets None
• Front Matter None
• Important Information Topic
• Support Topic
• Conventions Topic
• Related Documents Topic
• Shared Components None
• Variables Library Topic
• Images Image
• Topics Topic
• Maps Map
• Publications Publication
28. 28
The Folder Structure – Shared Components
Widgets
Front Matter Shared
Images Topics
Variables Images Topics Maps Publications
29. 29
The Folder Structure – Folder Type
Folder Name Folder Type
Widgets None
• Front Matter Topic
• Shared Components None
• Images Image
• Topics Topic
• Variables Library Topic
• Images Image
• Topics Topic
• Maps Map
• Publications Publication
41. 41
The Folder Structure – Element Type
Element Name Element Type
Release Notes Publication
Installation Guide Publication
User’s Guide Publication
Widgets Publication
43. 43
The Add-ons
• Use the Conditional Manager to set up the
conditions required for the project
– Mac / Windows
– HTML / PDF
• Use the Translation Tool to set up translation
process
45. 45
The Outputs
• Using a single source file to generate multiple
outputs
• Outputs like PDF, CHM, HTML, etc., can be
generated
• Apply conditions before generating the necessary
output
• Use draft markers and watermark at review stage
and remove them before generating the final
output
