Giving names to images/sections/help topics is something tech writers do a lot. To find just the right name is important – this is what defines an object. Understandably, certain guidelines exist for the file naming process. When you work on many projects, you will have to come up with a kind of style guide for naming files. Otherwise, it will become a mess very soon. Let’s take a look at some recommendations for naming files that will help you keep documentation projects organized.
Names Should Be Descriptive
This is the rule of thumb for naming any file. Description naming helps:
- Quicker understand what the file contains.
- Avoid ambiguity. If a name is descriptive, it is automatically unique, which means that you won’t misinterpret where the file belongs.
Test each file you name against this criterion. You should not spend any considered amount of time figuring out what’s inside – its name should speak volumes to you.
Try to Avoid Abbreviations
The point is to come up with a name, the meaning of which will still be clear for you in a year. When you tend to use abbreviations or shorten the words a lot, believe me, you won’t be able to tell what it means pretty soon. And, I am not even talking about others – how should other people understand the meaning behind it?
Think About Other People
When we are working on a documentation project, we mostly consider our own convenience. Imagine, however, that this project will be assigned to somebody else, or your peer will be included in the project to help you out with developing this user manual. Will this person be able to understand what is going on, judging by the file names? Your job is to make sure that they will.
Divide Words Inside Titles Using Underscores
Some people like to watch the world burn and jumble words together like twitter hashtags:
documentationprojectcopy.pdf
This approach gets the universally lowest readability score! The safest way for naming files where you need to use several words would be using underscores. You may never encounter issues simply using spaces either, but, just in case, try to think of underscores as the best practice. Spaces can cause issues since they are special characters, therefore, the file title can be transformed into something else, and the file can be handled incorrectly.
Use Words Rather Than Numbers
Numbers are often way less descriptive than words, that’s one point. Another point is that if you make a mistake, you’ll have to re-do the entire series of files. For example, you are creating a help topic about popup windows with some screenshots that you chose to name like this:
popup-window-1.jpg
popup-window-2.jpg
popup-window-3.jpg
popup-window-4.jpg
popup-window-5.jpg
You finish up the topic, review it, and suddenly realize that, actually, it would be great to add one more screenshot somewhere in the middle. If you chose to name them using purely descriptive names, that wouldn’t be an issue, but since you have numbers attached to each name, you will need to re-name almost every image to add a new one and maintain order. So, avoid numbers when you create and name screenshots.
Stick to Your Own Rules
Once you got the naming strategy figured out, you need to follow through with it, otherwise, what’s the point? 🙂 Consistency is what will help you boost velocity. As soon as you name and order your project files, the process of working with them will flow. You won’t need to go through a mess of names and folders every time you need something – well-named files are always easily found.
Conclusion
Optimization is a great habit. And, not only for projects that you feel you will be working with for a long time, but it is rather just a great way of doing things in general, always looking for ways to improve things. Remember that small things like naming files actually constitute the entire help authoring process and deserve attention.
Good luck with your technical writing!
ClickHelp Team
Author, host and deliver documentation across platforms and devices
