There are plenty ways to polish things as you build and maintain an environment for structured authoring. One easily forgotten detail like this is your choice of the principles for how you name content, which provide great potential benefits. The filters in DoX CMS make names especially important for quickly finding the correct pieces. This is not the only reason to account for how you name things, though.
Just compare the names ‘Tallenna’ (‘Save’ in Finnish) and ‘ui_command_save’ for the same variable related to a part of the UI. They approximate the extremes of the range of available options. But what makes one of them better than the other? (Yes, language is a consideration.)
Component names
In this context, components refer to all parts of a content management system that you use to compile a publication. Topics are the obvious example but their names already correspond to the titles of associated sections. Meanwhile, tags, topic trees, element classes, variables, and language groups each have their names, too. The same principles apply partially to translations projects, too.
Classes
When components are ordered alphabetically, such as variables in the text editor, or when you can filter for them, classes built into their names make it easier to find the correct components.
Such classes are based on the use of keywords as prefixes. You can include multiple layers where subsequent keywords represent subclasses. For their part, such subclasses help delineate the search further when you depend on alphabetical order, for example. And otherwise, each position would have too many alternatives that start with the same letters.
Predictive compartments
But why is the use of classes and their subclasses actually so important?
They are a predictive measure that accounts for the potential future proliferation of components.
When there are at most several dozen of a given type of component, you can still browse them to find the correct ones for each situation with little trouble. But with time, their number can exceed hundreds and you should anticipate this early. You cannot rename most of them without then having to locate each location that includes them and replacing those values, too.
In practice, classes provide compartments which help you find the values inside them with that same quick browse through them. Each of these compartments have few enough names that start with the same letters to make a quick glance instead of a careful look enough to identify the correct components. For example, with classes, there ought to be fewer consecutive components that start with the same two to three letters, which would make those few letters enough to recognize the correct components.
Keyword selection
Which keywords you designate for different classes matters.
In particular, when there are several layers of classes, you should stop and consider the appropriate level for each distinction.
Such keywords for classes might include
- button,
- command,
- company,
- contact,
- dealer,
- icon,
- menu,
- resource, and
- UI.
Let us assume that this list is the result of a brief preliminary brainstorming session. The writers here know that they need variables at least for parts of the user interface and for contact details.
For me, the next step would be to go through them again and consider whether there are any bad fits. As part of this process, you can also consider the axes along which you add distinctions. One such important distinction is whether you base classifications on functional or presentational differences. I mainly recommend that you use the former even though the involved differences between these two alternatives are not always obvious. For functional differences in particular, you must then consider which distinctions you focus on.
In this example, I would remove button as a keyword. Its applications feel too restrictive and you may need to use the same variable in other contexts, too. However, if you want to consciously keep the values for buttons separate from the same expressions in other contexts, this keyword would remain helpful. Resource as a keyword is also likely too general and vague for a meaningful distinction to be grounded in it.
The goal is to have the most general classes as the primary distinctions used at the starts of these names. The correct higher order classes are not always obvious. UI (user interface) is clearly the superclass for icons and commands. But for example, (your) company and contact (details) intersect as classes instead of one providing a proper sublclass of the other. In situations like these, you should account for the other required distinctions.
For example, if the contact details for multiple companies are a priority, I would set contact details as the higher order class. Alternatively, if you only need to include your own contact details and you also need to use variables for your company logo, the names of people in different roles, and so on, you should set company as the higher order class. Of course, you can also split these details across multiple superclasses by having your own company be a subclass in each of them. This option is more open-ended when it comes to expected needs for extensions.
I would thus use this schema for this example:
- UI
- Command
- Icon
- Menu
- Contact
- Company
- Dealer
I recommend that document these keyword-based class hierarchies in a way which is also compatible with further extensions to the number of classes. Such documentation helps keep their use consistent as well. Although I used embedded lists above, I recommend tables where classes are rows and their hierarchy is expressed with columns, instead.
Formulations
Specific formulations also matter. Users must be able to locate the correct values effortlessly and to use them error-free. You should not accidentally make either task harder.
Letter case and separators
Each layer should be clearly distinguished from the rest. Several methods to achieve this are available. You can also combine different methods to express different kinds of distinctions. For example, I have at times used an underscore only to separate the baseline value from the classes that preceded it. This makes it clear which sections are keywords and which constitute the baseline value. Baseline values that include more than one word are often required at least for the names related to parts of an interface.
Some alternatives for how to do this include:
- punctuation-marks: You can use symbols such as hyphens, underscores or hash signs (especially for keywords).
- CapitalLetters: Each part or word is capitalized.
- camelText: Parts other than the first are capitalized.
The defining factors are the ease to replicate such formulations and how well they match their use cases. For example, capitalization and abbreviations rarely mesh well and this option prevents the use of subsequent abbreviations unless you introduce an exception to the rule for them. Any such exceptions muddy your system and make it harder to remember the correct procedures. This makes lowercase only the better option. Then, users no longer need to consider which letters to capitalize.
Intelligibility
Users must understand each expression in use for this. The main challenge to this which I witness the most is the use of Finnish for names. Current users may enjoy them but this effectively denies you the option to ever hire people who don’t speak Finnish for the role. Or at least unnecessarily makes their work considerably harder. Most of the technical writing that I see is originally done in English, regardless.
Intelligibility can also be hampered by, for example, overuse of abbreviations and jargon. There are times when such language is necessary because oversimplification weakens the cognitive connection with the exact referent. Regardless of which extreme causes the issue, the more that users must interpret the expression, the less intelligible it is for these purposes.
Words that look too similar can also have limited usability as parts of these names. This is less of an issue for natural languages but it remains noteworthy. Relevant factors include similar length, easily confused or even just similarly shaped letters, and matching sections. For example, the English words experience and experiment take more looking than just a momentary glance to distinguish, which also increases the risk of incorrect inputs. They are obviously two different words but the only difference in their syntax consists of the last four letters in each. And these final letters for both include the letter e. The letters n and m also consist of similar shapes.
Such similarity is specifically a major problem for codes, though. Codes usually lack the immediate recognizability that comes from personal experience, which familiar expressions in natural languages have. They must thus be processed one symbol at a time until the user observes at least some patterns which help with recognition. For example, the product names of a certain speaker manufacturer from Iisalmi or Sony headphones include such patterns. But you must learn them to quickly pay attention to the correct details and to anchor each product code to the correct notion.
Memorability
Memorability and intelligibility are different things but both depend on sufficiently distinct expressions and clear referents. Intelligibility itself helps with memorability in part because an an easily understood expression is often also easier to remember. Its clear referent helps form and maintain a memory trace. This makes clichés and default expressions good options because they are often already associated with well-formed cognitive models.
Patterns and rules contribute greatly to memorability and the simpler they are, the better. Make sure that you can express them simply, with a clearly matching referent for each detail. This principle refers not only to positions within a pattern but the actual values used there. For example, you can express size as part of a code with the actual values without their units, standard letters for size classes, such as S or M, or relative numbers for scale.
When memorability is a priority, you must avoid abbreviations. Any acronyms should be easy to pronounce or even match actual words. Simply leaving out some letters in each word is the riskiest option because users must then try and remember where these cuts were made in each name.
Despite how tempted you may be to just use UI elements’ current values for their names, for example, I recommend against it. This would permanently anchor those names on values which can become outdated and change. Simplified combinations of associated keywords are preferable. For new content, even if the value in use were ‘Add folder’, the component for this value may be better served by a name such as NewFolder. This makes it clear that it represents a new folder rather than adding an existing folder to a new menu, for example.
Element names
Besides independent components, individual elements can also require names. For actual elements, this involves their ID values. Element classes also belong here because their names are also tied to further functionality. You use elements’ ID values mainly for to target references such as links and content references (conref). These references can also have styles added to them at times, though. Element classes are mainly used for rules related to styles. These applications define the best practices for related names used for elements.
ID values
References to ID values make their memorability a priority. This way, you need not always go and check the exact values when you add such references. Although, you should always review the results. If you cannot copy these values onto the clipboard easily, to write them from short-term memory ought to also be reasonably doable. Natural language that you can partition with mnemonics is easier to remember than strings of symbols where you must remember each symbol independently.
You can also include keywords in these names. They contribute to memorability through introduced patterns. But you can also add rules for these values in style sheets to control covers, for example. Because you specify links’ targets with href values that include these ID values, you can use keywords to, for example, differentiate links to different kinds of targets with styles such as different text colors or superscript, like the letter t at the end of each link to a tutorial.
Unfortunately, DoX CMS does now allow you to add keywords to topics’ ID values. Rules that only target all of them are possible with specifications such as that the ID value must not contain any letters. You can do this with the help of a specification like :not([href*=”a”]) for each letter to express ‘exclude values which contain this letter’.
Element classes
Element classes are subject to all the same recommendations as other types of components. Their names should also account for their use with style sheets. Selectors that designate parts of attributes’ values let you add rules to more than one element class at a time based on keywords that their names include. This way, element classes that control tables’ column widths, for example, do not require that you repeat values if each of them includes keywords which express the correct column widths. Instead of exact values, these keywords can also include relative values such as narrow, wide, or half. You can specify default values for each of them based on the total number of columns in a table and, for example, separate values based on whether the value half is included somewhere for some column.
An element class like this could be called Table_5col_1wide_2narrow_3wide, for example. This value expresses that this is a table with five columns, where the first and third column are wide and the second one is narrow. The remaining two are left unspecified which divides the remaining width equally between them.
table[doxelementclass*="half"], table[doxelementclass*="narrow"], table[doxelementclass*="wide"], [doxelementclass*="half"] > table, [doxelementclass*="narrow"] > table, [doxelementclass*="wide"] > table
{table-layout: fixed;}
[doxelementclass*="_1narrow"] th:nth-child(1),
[doxelementclass*="_2narrow"] th:nth-child(2)
{max-width: var(--columnNarrow);}
[doxelementclass*="_1wide"] th:nth-child(1),
[doxelementclass*="_2wide"] th:nth-child(2)
{min-width: var(--columnWide);}
[doxelementclass*="_1half"] th:nth-child(1),
[doxelementclass*="_2half"] th:nth-child(2)
{width: var(--columnHalf);}
[doxelementclass*="_1narrow"][doxelementclass*="half"] th:nth-child(1),
[doxelementclass*="_2narrow"][doxelementclass*="half"] th:nth-child(2)
{max-width: var(--columnNarrowWithHalf);}
[doxelementclass*="_1wide"][doxelementclass*="half"] th:nth-child(1),
[doxelementclass*="_2wide"][doxelementclass*="half"] th:nth-child(2)
{min-width: var(--columnWideWithHalf);}
body {
--columnHalf: 50%;
--columnNarrow: 15%;
--columnNarrowWithHalf: calc(var(--ColumnNarrow) * (2 / 3));
--columnWide: 40%;
--columnWideWithHalf: calc(var(--ColumnNarrow) * (3 / 4));
}This is not the simplest solution ever because you must copy and adapt the selectors for each different column number. The example above has only done this for the first two columns. Split or merged cells can also break these rules. As such, you should have clear rules for when to use them.
Variables and calculations are not a necessary part of such specifications. However, they make it easy to derive some of these values from the rest and control them in one position each. The value for half width has a variable just in case because you may need to adjust this value for different publication formats and this allows that to only involve one position.
Summary
You should name both components and elements systematically. This helps you find them faster and reduces errors in their use. Finding the correct ones quickly is helped by the use of keywords. They also let you put the contents into compartments, particularly in menus which list those components in alphabetical order. Such subclasses make sure that values which would otherwise be easy to confuse are more likely to be separated to distinct positions on the list. They also provide trails of thought which users can follow when they do not remember the exact baseline values.
You must select and organize these keywords carefully to pave these trails and to anticipate future values. Start with the most general level of distinctions. When it is unclear which level among several alternatives is the highest, consider which classes are the most important to you and whether the same keyword can be included inside several classes.
Good formulations for names require consistency for both where you use capital letters and which separators you use and where. Whichever system you select for this, it must be uniform and clear to make sure that users remember how to do those parts correctly.
The words that you use should also be intelligible and memorable. Users must be able to recognize what those expressions mean without a need to consciously interpret them and to remember the correct expressions to follow the constructed trails of thought. Words that are organized closely together should not be too similar and you should avoid abbreviations. Any included codes should ideally contain clear patterns where users can learn related rules instead of having to remember individual values.
All these considerations can and should also be accounted for in elements’ names. They include ID values and element classes. In their case, these values and their parts can also involve forms of functionality which impose their own requirements. Memorability is even more important for ID values because you use them for references. Keywords included in both can also be used in style sheets to avoid the need to write the full values each time.