Conventions Discussion

Please use this page to discuss options and recommendations

Karen - to describe current convention

Current File Name Conventions for SAEAF 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 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: gov_* in gov subdirectory (for phase 2)

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

• saeaf_output_builds
• 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.

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.)
• 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