How to Name Files in a Technical Documentation Project

© 2011 Ugur Akinci
Naming files — it sounds like something easy to do, doesn’t it? But I know from experience: it can actually become a very complicated and tangled-up affair with productivity-killing consequences.
The root of the problem lies in the fact that the name should make sense not only for the creator, the technical writer, but for the Document Management system as well. This system can be something as simple as a common network drive accessed by other writers and end-users, something a little bit more sophisticated like a SourceSafe directory, or a full-fledged content and version management system like Agile.
The human users like NAMES that has as many words as possible, DESCRIBING the CONTENT of the file. For example: “Model_101_DoorLock_Configuration_Guide.pdf”.
Machines, on the other hand, love sequential, discreet, and numeric LABELS that points at a LOCATION or ATTRIBUTE (like directory address or ID number) rather than the CONTENT of the file. For example: “123_JNM_V1.pdf”.
The trick is to reconcile these two different demands in one compact formulation.
The solution I prefer answers both of these concerns.
Start with a MACHINE LABEL and then append it with some sort of CONTENT DESCRIPTION.
For example, here is a sample file name that I like:

786-ABC-V1_Voltage-Regulator-Guide.pdf

The UNDERSCORE character is a marker that tells me where the machine label ends and content description begins.
The first part tells me the file’s system label. The second part is for my own personal use. Without that part, “786-ABC-V1.pdf” would not tell me anything about “what this file is all about”, especially when I’m dealing with hundreds or thousands of project files.
What do you think about this system? Which naming template do you use? Feel free to share.

2 Comments

  1. Larry Kunz on January 4, 2011 at 6:18 pm

    Ugur, thanks for reminding us that it pays to give careful consideration to a file-naming scheme. The information architect or lead writer should consider setting up guidelines, like the ones you’ve given here, and asking all of the writers to use them.
    An added wrinkle is introduced when files are reused. A single file, for example, might be inserted into the documentation for several different machines. Or a DITA file might contain elements to be used (via conref or keyref) in many different places. I prefer to isolate these files in a special directory, with a name like /shared or /common, and give them names that indicate their functions. Examples: common_installsteps.xml or conref_products.dita.



    • admin on January 4, 2011 at 7:01 pm

      Excellent advice, Larry! I’m sure DITA-users will take notice your suggestion. Have a Happy New Year! Ugur