No matter how much technology advances, how to name files for easy organization and retrieval seems to be a perpetual challenge. One of the inevitable decisions to make when creating your content strategy is to develop a file naming convention for your thousands or millions of topics, graphics, maps, documents, and snippets you may end up storing in your component content management system (CCMS). So what are the appropriate CCMS file naming conventions?
It’s no small feat, but some good planning right from the start can save you a lot of work (and confusion) down the line.
A CCMS file naming convention has to take into consideration the answers to these questions:
- What CMS have you chosen?
- How are you planning to organize your content?
- What does your content need in order to be found?
- What is your single sourcing strategy?
- Do you have any limitations?
1. CCMS Selection
It may seem odd that your file naming convention depends on the CMS tool you’ve selected, but it makes a big difference. A simple example is the difference between a CMS that distinguishes between topic types in its architecture (like Vasont) and one that does not (like XDocs). Authors need to know what type of topic they are selecting. Where Vasont makes that an obvious pre-requisite to browsing/searching (you literally browse the task collection, for example), in XDocs the only way to determine topic type is by file naming convention. So authors using XDocs require either a suffix or prefix to indicate topic type, but for Vasont, that information is redundant.
XDocs: t_action_object_modifier_component, (For example: t_print_pdf_fancy_fmx, where the t indicates the topic is a task).
Vasont: action_object_modifier_component, (For example: print_pdf_fancy_fmx, where no topic type is indicated in the file name because this topic can only be stored in the task collection).
The ability to apply metadata and/or search and filter by existing metadata will also make a big difference in your choices for naming files. You may, for example, be able to drop the “component” part of the file name and tag it with metadata instead.
2. Organization
How you choose to organize your content in the system will have a big impact on your file naming. For example, if you are organizing your graphics in two different folders, one for install and one for UI, then your graphics won’t need those distinguishing file names. (See Organizing Your Content for more on using content tagging for better organization.)
However, if you choose a looser organization plan (a best practice, but not always practical), your file names may have to be much more stringent and specific.
3. What Does Your Content Need in Order to be Found?
A good CCMS file naming convention allows authors to browse through topics that may be closely related. This can be useful when they aren’t sure what content exists.
For example, you might group together the following topics in the following ways:
| Install a plug-in | t_install_plugin |
| Install a widget | t_install_widget |
| Upgrade a plug-in | t_upgrade_plugin |
| Upgrade widget A | t_upgrade_widget_a |
That lets all your “install” tasks be grouped together and all your “upgrade” tasks grouped together, then differentiated by the object, then by identifier (if there is one). For your content, it might make more sense to group content together by object first, then by action, so you would have:
| Install a plug-in | t_plugin_install |
| Upgrade a plug-in | t_plugin_upgrade |
| Install a widget | t_widget_install |
| Upgrade widget A | t_widget_a_upgrade |
Now, you have all your“plugin” tasks and all your“widget” tasks grouped together, regardless of the action. There are advantages to both ways of displaying the content. The best way to determine the right way for your content is to take 100 topics and try naming them both ways (also try suffix instead of prefix for the topic type if you need to include it), and see how authors will be able to sort and group their topics by file name.
4. Single Sourcing Strategy
If you have more than very basic re-use for your single sourcing strategy, you’ll also need to create a CCMS file naming convention for topics and snippets that authors need to re-use heavily. This could be anything from variables (components or names that often fluctuate but need to be consistent across deliverables) to warnings, notes, and boilerplates. Combine this with your organization approach to make it most useful to your authors. For example:
- Source for heavily re-used content: c_source_type_modifier (e.g., c_source_warnings_electrical).
- Legal topic to be re-used as is: r_topic (e.g., r_legal).
5. Limitations
You may have some limitations you need to consider when creating your file naming convention. For example, if you are creating UNIX man pages from your reference topics, those reference topics need to follow a specific format: command_name.numerical_type (e.g., list.5).
The Process for Developing CCMS File Naming Conventions
A good CCMS file naming convention is one that can meet author needs and stands the test of time. So it’s important that you take your time with it upfront and get it right.
At the same time, it’s important to let the naming convention grow. You never know what new products or companies you may need to incorporate next year or what new tools will change your strategy. If your existing convention becomes obsolete, make sure you take the time to let it evolve (intentional evolution, of course).
- Plan
- Test
- Revise
- Roll out to the team
- Collect feedback
- Revise
- Write down the convention
- Enforce
- Evolve
File Extensions
Remember to specify your desired file extensions. For DITA topics, it can be either .xml or .dita (in most cases, it doesn’t matter which one you use, but be consistent). For graphics, you may want to use the file naming convention to control the allowable graphic types and versions you want to allow.
Conclusion
In the end, your CCMS file naming convention has to be usable considering your content, your tools, your organization of content, and any special limitations you may have.
