How to name topics better when developing a new documentation?

Hi Scott,

Very appreciate for your timely reply.

Currently, our group name a topic based on its content or title so as to learn about the theme quickly. Finally we decided to choose the later, for it could save space. I have been thinking it is a little confused and hard to distinguish. In that case I would ask for help in this community.

Same with you, I prefer to design a set of ID rules and use topic ID as the file name. Though it is a little hard to decide what it is about. As we know, the structured FM support ditamap on the left, thus we can experience the same development process with unstructured book with chapters.

I am considering the two questions you provided. Yes, our target is mainly to display its contents and we also know it is difficult in maintenance later. Everything has two side.

Thanks again.

Hi Vicky...

The actual format you use to define topic file names doesn't really matter other than it should make sense to you and your group. The two examples you provide are essentially identical (other than casing and underscores) and will have no bearing on the validity of the reference to that topic. The thing to consider is what type of information is important to include in the file name.

- Do you really need an indication of the topic type? Is this really useful or not? Some people include it in the file name, and others put the files in a folder that indicates the topic type (and some do both). While some don't include this info at all.

- Do you really need to include the topic title in the file name? This can be a slippery slope. When you do use the topic title in some way in the file name, what do you do when the topic title changes? If you end up changing the file name, then you also have to fix up any references to that topic.

I tend to prefer to use non-human-readable file names, like using the topic ID (GUID) as the file name. I know this is hard to imagine, but you really shouldn't be browsing files based on the file name anyway. There may be hundreds or thousands of files in a folder, and it's unlikely that you will really be able to easily locate the file anyway. You'll probably need to use some type of search to find the file. And when opening files for editing, it's best to locate them from the map .. like you'd do when working on unstructured FM files .. open the book (map), then open the component within the book (map). The nice thing about maps is that you'll see the actual title of the topic, and the topics are in an order that makes sense (hopefully), grouped by sub-maps.

In the end it doesn't matter as long as you have rules for file naming that everyone understands and follows.

Cheers,

…scott