Conventions Discussion

Please use this page to discuss options and recommendations

Back to SAIF Editing Crew

Current File Name Conventions for SAIF DITA Topics

• Each topic filename corresponds to the title of the topic (with a few exceptions such as when I changed the title but not the filename). For example, "SAEAF Overview" is in the saeaf_overview.dita file.

The SAEAF topic files will be checked into the saeaf-dita\saeaf-dita-source-files directory in SVN using the following structure:

• Top-level topics (including executive overview): saeaf_* in main directory
• Glossary topics: def_* in glossary subdirectory
• Intro topics: intro_* in intro subdirectory
• ECCF topics: eccf_* in eccf subdirectory
• BF topics: bf_* in bf subdirectory
• GF topics: gf_* in gov subdirectory (for phase 2)
• Graphics: TBD_* in graphics subdirectory

The SAEAF output files (zipped html and pdf) also will be checked into the saeaf-dita\saeaf_output directory in SVN:

• saeaf_html_builds
• saeaf_pdf_builds

Comments from Eddie

• Intro topics are equivalent to concepts (introduction, overview, about), so we need to consider this in a DITA context. Basically anything that's descriptive, overview material could have a con_ prefix.
• I believe that the best practice is to use the information type in the name and use metadata to describe what the existing prefixes are currently describing. For example, an overview of the ECCF could have a con_ prefix (ex: con_about_eccf.xml), but the metadata would also include an ECCF attribute. Using this method, we aren't forced to have to use specific words in file names.
• Don't forget the shortdesc (short description) element. It can also aid in search.
• Overall, I believe that we should harness the power of metadata to make distinctions rather than relying on file naming prefixes for so many variations.

Comments from Karen (01-18-10)

The graphics are currently stored in the graphics subdirectory. Yes, I'm using the shortdesc element for each topic. For phase 2, I propose making the following filename changes:

• Append the con_, task_, ref_, or topic_ prefix to each filename. The glossary files already use a naming convention of def_.
• Leave the topic IDs unchanged.
• Use the "category" metadata definition to indicate whether the topic belongs (for example, intro, eccf, bf, gf).
• Keep the existing directory structure.
• Eventually expand usage of the metadata attributes.

Graphics Directory Structure and Naming Conventions

The graphics that are used for the SAEAF DITA project are stored in the saeaf-dita/graphics directory and use these name conventions:

• sa_* intro and eccf graphics
• bf_* BF graphics
• wi_* 2 working interoperability graphics
• rm_* 2 rm-odp graphics
• gov_* GF graphics

Note: If you have ideas for a better filenaming convention for graphics, let me know.

• Other options I've seen are to use a component identifier or to begin concept topics with con*, task topics with task*, and reference topics with ref*.

Comments from Eddie

• What about the graphic names beyond their prefixes? Do you have examples? I have often used dgm as a prefix for diagrams: dgmStairwayToHeaven = diagram of Stairway to Heaven (Note that if you're concerned about length, you can use camel case with no spaces.)
• <Karen's comments 01/18/10> Do you think the graphics should have a prefix for each framework or use a general prefix such as fig_ or dgm? Here are some examples of graphics names being used:
  • sa_wi_stairs.png
  • bf_accountability.jpg

• To distinguish frameworks, I echo my previous suggestion. Use the information type in the file name and use a metadata attribute that spells out Behavioral Framework or Governance Framework. If you feel that other prefixes are required, I suggest including *fw. gov is a risky prefix.
  • Suggested Examples:
    • Behavioral Framework = bfw_
    • Governance Framework = gfw_

• Here are sample file names for basic information types (concept, task, reference):
  • con_about_quick_search.xml
  • con_about_lexbig_server.xml
  • con_lexbig_overview.xml
  • tsk_performing_quick_search.xml
  • tsk_performing_advanced_search.xml
  • tsk_creating_widget.xml
  • ref_project_metadata.xml
  • ref_widgetmaker_function_list.xml
  • ref_widgetmaker_keyboard_shortcuts.xml

Collected Examples

Source: DITA Users (Yahoo Group)

Example 1

1. We do put the topic type in the file name (t_, c_, r_, and for conref files we use cc_, cw_, and cn).
2. We do not put the product name in the file name. We use folders to organize that information. We also use folders to organize the sections of information. Everything about imaging modes is stored in an imaging modes folder.
3. We use the topic title in the file name.

So, scanning with 2D would be stored in Imaging_Modes and appear as t_Scanning_with_2D.xml.

Example 2

Questions Asked:

1. Do you place the topic's type in the file name (e.g. task_creating_ditamap.xml)?
2. Do you put the product or guide name in the file name? On one hand I can see how this would be beneficial, but it could also lead to confusion if a topic is reused across multiple guides.

Answer:
No to both, but I do something that has a similar effect: I put the file into a "task" directory. I am fond of deep directory structures so it's not unheard of for a file to have a path like task/product/foo-o-matic/flossing_cats.xml.

Realistically, our filenames do reflect the content of the file, but if a file's scope changes (for instance, it now covers a suite of products) I am not rabid about changing the filename to reflect it. Tracking backreferences is a bigger evil in our setup.

This probably explains why I so dislike the magical file-suffix checks that DITA-OT does for *.ditamap for maps, image formats, *.dita/*.xml for topics, and so on. This is probably a necessary consequence of DITA-OT's heavy dependence on a filesystem. A DITA processor based entirely on URLs and HTTP would be an interesting exercise.

Related Pages

• SAIF Editing Crew
• Groundwork for DITA Adoption
• Metadata Discussion