Guidelines for Naming Files

As a technical writer, you likely work with a myriad of different files for each project you work on; a single document or document set can often be derived from dozens if not hundreds of source files, potentially created by dozens of people over a period of time. Couple that with working on multiple projects, managing document revisions, and last-minute document changes, and you likely face a challenge in just accessing and managing the files you need.

While file naming may seem like an insignificant detail, developing an intuitive, descriptive file naming system can help minimize file access and management challenges. What's more, developing such a file naming system--especially when a consistent system is not in place--can have added benefits, such as improving access through better searchability and browseability, and improving access for everyone who may, now or later, need to access project files. In this article, you'll find several tips and examples for naming files, which used individually or in combination, can help ease file access and management:

Use descriptive names
Use alphanumeric characters
Use underscores rather than spaces
Avoid numbering
Use short names
Be consistent
Use descriptive names At some point in a file's lifetime, someone other than you will have to find it. This may not sound like a problem for a small project, but as a project grows and as the number of files required for that project increases, finding a specific file becomes more difficult. You can avoid this problem by including a hint to a file's contents within the name of the file. Rather than using cryptic numbers or abbreviations, such as "45dhg21234-3.fm" for example, use descriptive terms or titles instead, such as "UserGuide.fm."

Use alphanumeric characters As you're developing a file naming system, avoid using special characters, including these:

\
/
:
*
?
"
<
>
|
(space)
%
@
+
-
Instead, use alphanumeric characters (letters and numbers). Although some special characters are relatively safe, keep in mind that some operating systems or programs may not recognize special characters or may "reserve" them for special purposes. Even if one operating system or program allows certain characters, others may not; Microsoft Windows, for example, doesn't accept the first eight special characters listed here. Bottom line: Avoid using special characters in file names whenever possible.

Use underscores (_) rather than spaces As mentioned, using spaces in file names can potentially cause problems for some users; however, using spaces between words in the file name can help readability. You can accommodate both guidelines by using an underscore (_) between file name components, rather than spaces: Panel_UserID.tif. This character is safe, and it provides the visual break between words and characters that can help readability.

Avoid numbering You may be tempted to use numbering when naming documents and screen captures, but this can pose some significant problems if you have to merge file contents or add new files between existing ones. Suppose you're working on a manual with six chapters. You create six different files, named Chapter1, Chapter2, Chapter3 and so on. Sounds logical, right? Now suppose that near the end of production, the Boss decides to merge Chapter 1 with Chapter 2, switch Chapter 3 with Chapter 5, and split Chapter 4 into two separate chapters. Using the numbered file naming method, you would have to rename all of the files; you may also have to update external files that reference those chapters, such as a book file or a TOC.

Complicating this scenario is moving and merging screen captures that are named with a numbering convention. In the above scenario, you would have to rename all of the files to fit into the new chapters and content. Or, suppose you need to add a new screen capture to accommodate a new menu or switch that developers just added. In adding a new screen capture, you may end up needing to renumber graphic files for an entire chapter or manual. You could simply leave things the way they are, but that only defeats the purpose of numbering. It will also confuse anyone who has to use those files later on.

For these reasons, avoid or minimize numbering and, instead, use descriptive names for the chapters and screen captures: Not "Panel023a.tif" but "Panel_UserID.tif." By doing so, you will often encounter less confusion in moving and merging chapter content and won't have the confusion of changing file name numbers. If you do use numbering, keep two things in mind. First, use numbering in combination with descriptive names so that you have a hint about the file's contents and purpose, as described earlier in this article. Second, be sure to append the numbers with "0"s. A sort by name on the following file names "File1," "File2," "File10," "File3" and "File200" would return the following order:

File1
File10
File2
File200
File3


Appending an appropriate number of "0"s would return more useable results:

File001
File002
File003
File010
File200


Use short names Back in the DOS and early Windows days, all file names had to be in a standard 8.3 format (eight characters for the name, a period, and three characters for the file extension). These days, a Windows file name can contain up to 255 characters, including spaces. While it may be tempting to use all 255 characters for a file name, you shouldn't, for a couple of reasons. First, some programs cut off long file names in dialog boxes, making the file names difficult to read or forcing you to resize the dialog box, if possible. Second, older programs may cut your carefully crafted file name down to the 8.3 format, turning VacationRequestProcedures2001.doc to Vacati~1.doc. Unless you know that long file names always work in your environment, consider devising a series of two-character or three-character codes and creating your file names based on those codes; for example, rename "UserID_Panel_Login_Screen.shg" to "LogSnUID.shg."

Be consistent You can more easily browse for documents in a directory if you construct the names consistently across projects and versions. For example, rather than naming one file "V2WidgetGuideIntro.doc" and another file "WidgetGuideIntroV3.doc," name them all using a consistent order of information. Which order is better? It depends on how documents are typically accessed. Starting with the broadest description (e.g., the type of document) to a narrower description (e.g., product name) to the narrowest description (e.g., the version of that particular document) would result in a directory listing such as this:

IntroGuideWidgetV1
IntroGuideWidgetV2
IntroGuideWidgetV3


which could be handy if documents are typically accessed by document type or product. Conversely, if documents are typically accessed by version, then providing that information first might be more effective, as in:

V2InstallGuide
V2IntroGuide
V2UsersManual


Such a convention might not be needed if you are using short file names or if you typically don't have many files within a directory; however, being consistent in naming files can aid users in locating files quickly.

While spending time searching for files or finding truncated file names won't put your projects in peril, such problems can be frustrating and time consuming. Although these file naming guidelines may not meet every file naming need or situation, they can help minimize problems that crop up late in the development cycle, help you (and others) access files more quickly, and help overcome challenges in managing files over time. With these file naming guidelines in mind, take time to examine existing file naming conventions, talk with people across the organization, find out what works and doesn't work, and then begin seeing how the guidelines mentioned here can help meet file naming needs. Then, document and use the file naming system, as doing so is key to its success; include file naming conventions in the company's corporate style guide or provide information separately so that others can apply the system consistently. The guidelines in this article should provide a good starting point for devising a file naming system

this article found here.