Naming Conventions

Put some thought into the way you name your folders and files, whether they are topics, snippets, images, targets, skins, etc. This is important not only for consistency, but also for potential effects on search results.

Word Separation

Many of your file and folder names are going to consist of more than one word. Here are some ways you can handle this:

  • Hyphens (Recommended) Hyphens provide visible separation between words and are recommended by some search engine optimization (SEO) experts.
  • Spaces Adding spaces between words is simple. However, blank spaces can cause issues for Web servers, particularly those running UNIX or Linux. Also, in the browser path field, the characters “%20” will be inserted between each word (e.g., Choosing%20a%20Cat.htm instead of, say, Choosing-a-Cat.htm).
  • No Spaces For best results with keyword recognition, it is recommended that you do not run keywords together in file names (e.g., choosingacat.htm). When keywords run together, there is a greater risk of the keywords not being recognized, as well as not being parsed properly by search engines.
  • Underscores While it is a common practice to use underscores in file names (e.g., Choosing_a_Cat.htm), many search engine providers and SEO experts no longer recommend it because the underscore is considered by some indexes to be its own word character. While it provides visible separation between words, one point to consider is that some search engines might take regular expressions such as "Choosing_a_Cat" and interpret it as "ChoosingaCat."
  • Periods It is recommended that you do not use periods (.) to separate words in file names. Periods are used by some computer systems to indicate different file extension types.

Case

You might choose to uppercase or lowercase in your folder and file names. Because some major search engine providers run indexing systems on case-sensitive servers (e.g., Apache, Unix, and Linux servers), whether a file name is written in lowercase or uppercase can make a difference as to whether the file is indexed. For example, a page named "choosing-a-cat.htm" may be interpreted differently from "Choosing-A-Cat.htm." It can also lead to search engines creating duplicate page entries, which can result in error codes when users click links, as well as penalties for content ranking. While it is difficult to predict how each and every search engine will handle a file name, it is good to pick your file naming convention wisely and then use it consistently.

Length

Because file names are part of a URL, studies show that the general rule of thumb for page URLs is that shorter URLs are better. For example, a file named "choose-a-cat.htm" would be a more compelling link for an end user to click than a file named "how-to-go-about-choosing-a-cat-or-a-kitten.htm."

Key Words or Letters

You might consider adding key words or letters at the beginning or end of certain names to make them easily identifiable and organized. For example, perhaps you have created 50 snippets that are specifically intended for a feature called “transmission.” Therefore, you might want to begin the name for each of those snippets with that word (e.g., transmission-getting-started.flsnp, transmission-initial-steps.flsnp, transmission-note-1.flsnp).

What the MadCap Documentation Team Does

Here is what we do for naming conventions:

  • Hyphens For both file and folder names, we use hyphens between words.
  • Title Case We use title case when naming our folders and files (e.g., Creating-Project.htm, rather than Creating-project or creating-project.htm).
  • Length There are some topics that have somewhat long headings out of necessity. However, even in those situations, we try to limit the length of the actual file name, leaving out unnecessary or minor words, such as articles (e.g., Excluding-Javascript-CSH-Calls-HTML5.htm, rather than Excluding-Javascript-for-Context-Sensitive-Help-Calls-in-HTML5-Output.htm).
  • Keywords and Letters For some file names, we use certain keywords or letters. For example:
    • For snippets that consist solely of an example, we begin the files with the word “Example” (e.g., “Example-Responsive-Content.flsnp,” “Example-Maximum-Concurrent-Builds.flsnp”). It just makes it easier to find and identify them.
    • We have many troubleshooting topics that are different from most of our other topics. So we will start the name of each topic with “TS” (e.g., “TS-Condition-Tags.htm,” “TS-PDF-Output.htm”).
    • For small images of buttons in the user interface, we add the letters “btn” at the end of the image file name (e.g., “Save-btn.png,” “Search-btn.png,” “Font-btn.png”). This tells us at a glance exactly what kind of an image it is without having to open it.