Decide on data element naming conventions

What should I call this data element?

One of the advantages of template development in XpressDox is that it is not necessary to spend a lot of time deciding on names for data elements.  You can create a good first-time template just by plunking in fillpoints like «surname» «Address» «First_Names» «salutation» and away you go – an automatic interview will be created and you can capture the data and merge it into the template to create whatever document it is.

That’s good as far as it  goes – you can get started with XpressDox very quickly.  You don’t have to design, even conceptually, all the templates and their interactions and create a “data dictionary” before you get going.  Just make templates and keep going until they’re all finished.

Take care to use the same data element names where possible

The problem is that without some help, the fields that you typed as «surname», «First_Names» on the first template end up as «Surname» and «Firstnames» on one or other later template.  And, because the field names are really XML data element names, surname and Surname are not the same thing, and definitely not First_Names and Firstnames. Later on when you re-use data, you want those data element names to be consistent. Also when designing packages of templates, or even code templates that you can re-use, having consistent data element names is key in this process.

Get help from the Command Assistant (Command Editor)

Now, XpressDox does provide quite a lot of help in getting a consistent set of data element names, mainly via the Command Assistant (also known as the Command Editor), which enables the display of already-chosen data elements in a way that the template author can re-use them correctly.  However, experienced template authors tend to want to use just the keyboard and type all of the XpressDox fillpoints without having continual recourse to the Command Assistant.

Decide on a naming convention

For no other reason than this, it is useful to start off on a large project (i.e. many templates and/or many data elements) by deciding on a naming convention for the data elements.  This does not mean that you need to decide on all the data elements up front, but that you decide on how you will assign a name to each new data element that you need to create as you go.

What follows is a set of suggestions (backed up by many lessons over the years from the school of hard knocks) rather than a set of rules. Probably you could add your own or make your own adaptations.  Even so, when you design a set of naming conventions for your organization, then they MUST become rules, and all template authors in your organization MUST abide by them – otherwise chaos will be the rule.

Rules for naming conventions

Here follow a set of rules (in addition to the obvious one, i.e. that data element names should conform to rules for XML element names), although the first one is a kind of meta-rule:

1. You should have a data element naming convention, even a bad one is better than none.
2. Call your data elements what they are.   For example, if a data element’s value is an interest rate, call it InterestRate, not Interest and not Rate.  Even better, call it InterestRatePercentage.
3. Try not to abbreviate.  This and the previous item go together:  usually you will abbreviate to save typing, but abbreviations often end up being cryptic and after all, the Command Editor is there to help get the name right.  Think about how someone else will read your template and either understand it or not.  And remember, that “someone else” is likely to be yourself in a few weeks/months/years and then you won’t remember that you abbreviated InterestRate to Int and InterestAmount to Intrst. You can of course use Captions to make the data element more readable on the interview, but that still does not mean Intrst will be a meaningful data element name to you as the template author.
4. Because of Rule 2 you will end up having many data element names which consist of more than one natural language word (like “interest rate” becoming InterestRate or Interest_Rate).  You need to decide how you will designate and delineate those words.  My own preference is to use so-called Pascal case, whereas others will separate the words with an underscore, and have different rules regarding whether to use upper or lower case at the start of each word in the name.  A side-effect of using underscores to separate words in a data element name is that when the interview is constructed, the underscore is rendered as a space when the data element name is used as the caption, and this often dispenses with the need for an explicit Caption.  Almost universal, though, is an abhorrence for using ALL CAPITALS which tend to make the marked up text look very noisy.

That’s it – one meta rule and three rules.  Easy enough to remember when there are only 3, but worth the effort in the long run.