Conventions Discussion
Please use this page to discuss options and recommendations. Updated last: 11-01-10
Contents
Current File Name Conventions for SAIF DITA Topics
Each topic filename corresponds to the title of the topic. For example, "SAIF Overview" is in the saif_overview.dita file.
The SAIF DITA topic files will be checked into the saif-dita\saif-dita-source-files directory in SVN using the following structure:
- Top-level topics (including executive overview): saif_* in main directory
- Glossary topics: def_* in glossary subdirectory
- SAIF Introduction topics: intro_* in intro subdirectory
- Enterprise Conformance & Compliance Framework topics: eccf_* in eccf subdirectory
- Behavioral Framework topics: bf_* in bf subdirectory
- Governance Framework topics: gf_* in gf subdirectory
- Information Framework topics: if_* in infof directory
- Implementation Guide topics: ig_* in iguide directory
- Practical and Operational SAIF topics: TBD
- Graphics: stored in graphics subdirectory
The SAIF output files (zipped html and pdf) also will be checked into the saif-dita\saif_output directory in SVN:
- saif_html_builds
- saif_pdf_builds
- saif_word_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. <KGS> Yes, I'm using the shortdesc element.<KGS>
- 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.
Phase 2 File Renaming Plans
For phase 2, I propose making the following file name changes:
- Rename all 'saeaf' strings to 'saif' in the DITA and graphics file names.
- Rename all 'saeaf' strings in directory names to 'saif' except for the top-level saeaf trunk name.
- Make graphics file names more consistent.
- Use the "category" metadata definition to indicate whether the topic belongs (for example, intro, eccf, bf, gf).
- Keep the existing directory structure.
- Expand usage of the metadata attributes, especially for tracking version and search keywords.
Future plans:
- We plan to explore the possibility of using non-intuitive file names (UUIDs) in the future, similar to what IHTSDO plans to do. This work will require scripts for converting and displaying file names, coordinating file names with the Publishing group, and finding out from IHTSDO about the processes they use.
Graphics Directory Structure and Naming Conventions
The graphics that are used for the SAIF DITA project are stored in the saif-dita-source-files/graphics directory and use these name conventions:
- SAIF_* Concept maps and SAIF overview graphics
- bf_* Behavioral framework graphics
- gf_* Governance Framework graphics
- intro_* Intro graphics
- sa_* ECCF graphics
- infof_* Info Framework graphics
- iguide_* Implementation Guide graphics
- exmp_* SAIF Examples graphics
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_
- Suggested Examples:
- 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
- We do put the topic type in the file name (t_, c_, r_, and for conref files we use cc_, cw_, and cn).
- 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.
- 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:
- Do you place the topic's type in the file name (e.g. task_creating_ditamap.xml)?
- 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.
