ItsOn Micro-Content Strategy

One of my first tasks I was given when I began at ItsOn was to review all the UI content for the web application that it was building. In talking to the programmers involved, I found that all the UI content has been externalized (good!), but it was not organized, optimized, or consistent (bad!).

I found also that the content itself was in a bunch of PHP files. Each file was a PHP associative array, with each element in the array containing a key and a value. The key was what was referenced in the application code, and the value was what was rendered when the application was run.

Content Inventory

My first step was to do a complete content inventory. All of the application source files were in Git, so I got some Git account credentials and had one of the programmers teach me the Git command I'd need. I identified the PHP files that contained all the UI content, of which there were several, and extracted all the values from all the key-value pairs.

Content Analysis

The next step was ti figure out what to do with all this content, which was several hundred text strings. I had an idea, and as it turned out, this idea worked.

I dropped all the text strings into a spreadsheet. And then I did what looking back seems to be drop-dead simple: I sorted the column.

All of a sudden, issues jumped out at me. Duplication was one. I saw many text strings that were repeated, sometimes more than a half dozen times. That means when a text string was needed by a programmer creating some new feature, that programmer just created a new key-value pair and added it to one of the PHP files, rather than looking to see if that text string existed already.

I also found many instances of almost-duplicates. That is, text strings that said the same thing, but in a slightly different way. (I also spotted the occasional typo.) And I found many instances of phrases and sentences that were not grammatical or consistent.

Content Strategy

Once I organized all the content strings, I could start fixing them. I removed all the duplicates. I took the similar ones and made one version. I fixed grammar. I fixed grammatical patterns. All of this is what I call micro-content strategy. Even two-word phrases that go in menus need to be consistent. For example, you might want multi-word menu commands to be verb-noun. So you make that consistent. And that's part of what I did.

One of the things I made sure I did was to document everything, especially for the key-value pairs that I deleted. Members of the programming team had to go fix code and replace keys that were no longer being used.

Finally, I developed a short style guide, which I added to the internal Product Documentation wiki. This is what I wrote:

UI Text in [ProductName]

UI text strings in SDC are stored in PHP files as associative array data in key-value pairs.

Keys for UI Text Strings

UI text strings are values in key-value pairs stored in external resource files. The resource files are divided into content types, which are further classified by the structure of key content. The three resource files are:

  • forms_locale.php: Strings for widgets that commonly appear in web forms, such as buttons, text fields, radio buttons, lists, labels, and so on, typically what users interact with.
  • messages_locale.php: Messaging, including error, status, and confirmation messages.
  • content_locale.php: Everything else, including text strings for window and dialog box titles.

There's a 4th file as well: tokens_locale.php. This file contains text tokens that are reused in many text strings.

Keys should contain a classifier, followed by a hyphen, followed by an optional sub-classifier, followed by a unique identifier that is semantically useful in identifying the content of the value, with all except for the classifier separated by underscores. The classifiers we use:

In forms_locale.php:

  • btn- (The text on a button)
  • input- (the label for any text field where users input data)
  • label- (the label for widgets where users interact but don't input, such as drop-down lists, etc., as well as labels for groups)
  • option- (text for radio button or check box options)
  • hlp- (helper text)

In message_locale.php:

  • message-confirm_ (letting users know that they have accomplished something)
  • message-error_ (letting users know of problems)
  • message-notify_ (letting users know when something requires their attention)
  • message-status_ (letting users know state)

In content_locale.php:

  • column- (column header text)
  • nav- (navigation test, including menus and breadcrumbs)
  • title- (text in window and dialog box title bars)

The identifier should be semantically useful. Like with variable names, identifiers should give a clear cue as to its content (value).

Organizing UI Text Strings

In each file, key-value pairs should be grouped by classifier. In each group, key-value pairs should be in alphabetical order by key. This will help programmers find values to reuse or make sure values do not exist when new ones are needed. Organization such as this will better show existing content patterns when new content is needed.