Naming conventions of topics, etc.

[Kat se gat]

Let's say I have a folder called Fred and in that folder I have, say, 30 topics. When you seasoned pros create your topics do you adopt any particular type of naming convention for your folders and topics? Likewise for other resources and so on. My first real Flare project is beginning to make sense but I've got this nagging feeling that as I add more and more topics I might end up diluting things and making my job harder. Right now it's holding up but if I go much further I might end up creating problems. If I can put some best practices into effect now they might serve me well in the future. Any suggestions?

[kwag_myers]

I've yet to have a project that required folders within the Content folder, but I can see where a larger project (200+ topics) might require this.

My convention is to make things as intuitive as possible. If a project has a very obvious section (Fred), I use a prefix/suffix in the topic file name indicating that it belongs to Fred, f_overview.htm or overview_f.htm. The idea being that anyone looking for the Overview topic for Fred would most likely look for a file starting with either F or Overview. The same applies to images, toolsIcon_f.png.

[RamonS]

A naming convention is highly recommended. Which one that is depends on how you want to structure the content (content typing). The biggest point to drive home is consistency, the naming scheme might be not great, but it will help as long as everything is named consistently. Also, my suggestion is to use numerical indices rather than letter based. I agree with Kat se gat on the approach, but recommend giving "Fred" a numerical index. Why? Our alphabet has 26 letters, once you go past 26 items you need to come up with letter combinations or add numbers or something. So you are better off starting with more than just one letter as a code.
In one project I exclusively used numerical names based on a numbering schema for area/action/topic/bookmark/item. While that worked for me a file name of 003004027001.htm means nothing to anybody else. For that reason I would not do it like this again, the only benefit was that file/bookmark name and map ID were identical. While I would keep some sections numerical only, the first portion would be something more descriptive. Up to five (alpha) characters might be enough. Anything in area "Fred" would be prefixed with "fred", anything about Users would be prefixed with "user", anything in User Management is then "usrmt", etc. The trick is to be verbose enough to make sense out of a file name, but concise enough to not run into any pesky (Windows only) file and path length issues.

[lizat]

Hi Kat,

I agree with Ramon but would be even stronger by saying that a naming convention is essential! What you need to think about is "how are you going to use the name" and therefore what information is important in the name. Apart from the obvious use of uniquely identifying the topic some uses for the name might be:

• to indicate the contents of the topic
• to differentiate the topic from another that is similar
• to include some specific information that is useful when browsing the lists in Content Explorer
• to show the topics in a given sequence or position a particular topic, such as at the top of the bottom of the topic list e.g. using underscore will put is at the top, I use "zzz_" to get it at the bottom
• to see the category of the content easily - but this could be done using folders
• to see the version

You may want to do one or all of these things. Some simple recommendations:

• Use English so it's obvious
• add a numeric id if you want to force sequence and decide how many digits maximum then use leading zeroes to ensure sorting is correct
• remove spaces and use camel case i.e. upper case letter in the name (to indicate new word)
• consider length, otherwise you run into windows constraints as Ramon suggested; I have some recognisable standard abbreviations I use as it us easy to end up with inefficiently long names, and remember the end user doesn't see the file name (unless it's a download)
• sometimes it's useful to have a prefix if you need to group similar things together

I often have process models I am sharing in a guide and I will end up in a real pickle if I didn't have a convention. Here is a recent example that makes sense to me:

• FOLDER: 1002_ManageRecruitment
  • 1012_MgeRec_Overview
  • 1012_MgeRec_Diag
  • 1012_MgeRec_Desc
  • FOLDER: PublishVacancy
    • 1005_GetFundApproval
    • 1073_RevMaintVac
    • 1028_ChgVacStatus
    • 1204_PubVac
  • FOLDER:FillPosition
  • etc...
• FOLDER: MaintainWorkforce
  • etc...

You will need to decide how you do things for yourself but the last thing worth saying is that even if you get it 'wrong' and decide you need to reorganise Flare is really good at allowing renaming and resetting all existing links.

Hope this is some help.................................. liz

[Kat se gat]

Flareians, thank you most kindly.

[kevinmcl]

Hi Kat,
...

I often have process models I am sharing in a guide and I will end up in a real pickle if I didn't have a convention. Here is a recent example that makes sense to me:

• FOLDER: 1002_ManageRecruitment
  • 1012_MgeRec_Overview
  • 1012_MgeRec_Diag
  • 1012_MgeRec_Desc
  • FOLDER: PublishVacancy
    • 1005_GetFundApproval
    • 1073_RevMaintVac
    • 1028_ChgVacStatus
    • 1204_PubVac
  • FOLDER:FillPosition
  • etc...
• FOLDER: MaintainWorkforce
  • etc...

.................................. liz

Speaking of "First World Problems"... I find that having a nicely navigable naming convention like yours - coupled with the multiple layers of nested folders under Content - causes the Content Explorer pane to be too skinny to actually see the filenames. That is, if the Content Explorer is anything like its default width, all files have the same name, because the unique portions are too far to the right to be displayed. If the Content Explorer pane is stretched enough to show what's needed, then the editor and other useful panes are too cramped. I thought undocking some panes would help, but I keep wanting to swat them like annoying insects.

The space problem is exacerbated, for me because I work pretty-much exclusively via Remote Desktop to my Flare instance in a VM on our Techpubs server. I guess i just need to ask our Admin to bump up the RD and VM resolution/display size that gets served.

Anyway, I went for some very cryptic prefixes, to shorten topic names, but now I forget what I meant by some of them, in areas that I don't touch very often.
So, whatever naming convention you choose, think ahead about how viewable it will be in confined spaces and be sure to document (if only I could remember where....) the meanings of your naming conventions.

If you can't be a beacon and an example for others to aspire to, at least you can be an example of what not to do.... er.... ta-dah!

[awells12]

Another good practice from a technical standpoint is to avoid using URL-unsafe characters in the topic filename if you are using any web-based outputs. We recently had a problem with one of our HTML5 help files because one of the topic filenames contained a "&".