Naming Conventions for SmartDocs Content

Following some best practices when naming your SmartDocs content makes it easier to find, manage, and reuse your content.

The SmartDocs user interface displays reusable variables, reusable snippets, and conditional tags in alphabetical order. You can use this to your advantage to help group content that is alike together. By using a logical general-to-specific naming hierarchy, you can ensure that similar SmartDocs content is displayed together in the SmartDocs user interface.

Reusable Variables

If you have a set of reusable variables that contain company related information (company name, address, etc.), and you have multiple variations of some of this information, such full company name, abbreviated company name, corporate phone number, country-specific phone numbers, etc.

Here are some poor choice examples for naming these variables:

• Abbreviated Company Name
• Canada Office Phone Number
• Company Address
• Corporate Phone Number
• Europe Office Phone Number
• Full Company Name
• Information Email Address
• Support Email Address
• United States Office Phone Number

As you can see, it's difficult to determine how many variables you have that contain company address content because there is no logical order. Instead, you should use a hierarchical naming convention to help group similar variables together.

Here are the same variables renamed using this best practice:

• Company_Address_Canada
• Company_Address_Corporate
• Company_Address_Europe
• Company_Address_USA
• Company_Email_Info
• Company_Email_Support
• Company_Name_Abbreviated
• Company_Name_Full

Now your reusable variables are nicely grouped in a logical fashion. This makes finding and reusing your variables quick and easy.

You will also notice that we used underscores instead of spaces in our variable names. Although spaces are certainly acceptable and supported by SmartDocs, we opted for underscores because this makes variables easier to identify in document content when they do not have a value assigned.

For example:

Reusable Snippets

We can follow the same general-to-specific naming hierarchy described above to name our reusable snippets. This will ensure similar reusable snippets are always displayed together in the SmartDocs user interface, which will streamline browsing and filtering through search results.

If you have numerous snippets that contain reusable financial information, such as balance sheets, incomes statements, and stock holder information. You could name these snippets as follows to ensure that all financial snippets are grouped together by year:

• Financial - 2010 - Balance Sheet
• Financial - 2010 - Cash Flow Statement
• Financial - 2010 - Income Statement
• Financial - 2011 - Balance Sheet
• Financial - 2011 - Cash Flow Statement
• Financial - 2011 - Income Statement

If you prefer, you could use underscores or spaces instead of dashes. It's all a matter of personal preference. The important thing is that your writing team adopts a standard naming convention that follows a general-to-specific naming hierarchy whenever possible.

Other SmartDocs Content

You can follow similar naming conventions for other SmartDocs content, such as conditional tags and document snapshots to achieve a similar result. Using simple naming conventions can go a long way to helping your writers easily find and manage your SmartDocs content.