Question about content in UI strings

[Rahel Anne Bailie]

A former client pinged me to ask about best practices for populating UI strings with content. I have seen quite the hodge-podge of methods over the years, and wondered what *good* practices are out there. Here are the options I've heard/seen to date:

Worst option: Developers enter some text on their own.

Second-worst options: 

Marketing comes up with some text and gives it to the developer to enter.

UX comes up with text and give it to the developer.

Middle-of-the-road options (but not terribly efficient): 

UX comes up with text and stores it in [one or more] resource files that the developers use to suck the text into the UI

TechComm comes up with text and stores it in [one or more] resource files that the developers use to suck the text into the UI

Best option:

TechComm manages the UI text in a CCMS/HAT, which keeps the content coordinated with all the rest of the help content, and exports to an area where the text can get sucked into the UI

What are the variations you've seen and what do you consider best practice?

Rahel Bailie

[Rick Yagodich]

Rahel

There are two parts to this question (even if you didn't realise it), so I will split and answer separately.

Where/how should these UI strings be managed?

The answer here runs pretty much in line with your best option. They need to be managed in a system from which they a fed/pulled into the application that will actually use them.

The problem I have most encountered with this is that often every individual label is given its own field, so you end up with significant duplication (or triplication, etc) of labels, which then means it is extremely easy for them to fall out of synch. So the key is to reference the same label field for multiple instances of the same functional label.

Of course, these values need to be input somewhere. The critical detail here (I have used it very successfully with clients) is that the fields used to manage this information must themselves have very clear and descriptive labels. For example, a "Submit" button label could have a management field label of "Label for confirmation/submission of forms". Actually describe the function of the label, which will generally indicate whether it is descriptive or action-based. For one recent project, 95% of the fields had longer management field labels than the UI labels themselves. But these descriptive fields are vital to translation - and they should be sent with any translation, to provide context.

Of course, you then end up with the recursion that the UI field management labels themselves need to be managed. Clearly, before you get into a loop, developers need a management interface that allows them to create new instances of labels, with keys (the coding reference for that label) and the ability to manage the management label, which should be provided by someone who understands what the label is for (especially if the developers' mother tongue is different).

The second question is Who should manage the labels?

While I can appreciate your take that it is tech comms, that is the correct answer only in a very specific scenario.

The correct answer depends on who the UI labels are aimed at. If they are front end, than it is UX or CS (or a collaboration between the two). If it is for the authoring environment, then it is AX or (if you don't have that function) UX or the authors themselves.

I fully agree that tech comms need to use the same labels as are in the UI, so their systems need to pull the same values in from the same storage. Of course, it gets nicely more complicated if you then need to support version control at this level, because the documentation for the previous release needs to still show the old version of the label text…

 - R

--
You received this message because you are subscribed to the Google Groups "Content Strategy" group.
To unsubscribe from this group and stop receiving emails from it, send an email to contentstrate...@googlegroups.com.
To post to this group, send email to content...@googlegroups.com.
Visit this group at http://groups.google.com/group/contentstrategy.
For more options, visit https://groups.google.com/d/optout.

[mbaker.analecta]

I agree with Rick. I would make a couple of further points, though. The distinction between the middle of the road option and the best option only exists if we presume that to manage a file means to own it. This is an outdated notion in a networked era. Source control systems impose certain limitations and guarantee certain properties or operations (like version control) and they allow external systems to add, delete, and modify files using certain protocols. This in no way precludes an external system from managing such a file within the source control system.

So the CCMS should be able to manage a resource file in development's source control system, and do things like trigger a workflow when a file is changed externally. This can be used to manage collaborative authoring of texts and labels.

This is a functionality with implications way beyond this particular issue, however. Tech pubs (and other functions in the organization) should be able to set triggers on all kinds of source code files for a large number of purposes.

I don't know how many current CMS and CCMS products provide this functionality, but to me it should be a must have on any CMS shopping list that it be able to manage any file with a URL, and that it should have specific support for accessing popular source control systems. Only being able to manage what you store yourself is simply an outdated idea.

Mark

Sent from Samsung tablet

-------- Original message --------
From Rick Yagodich <ri...@think-info.com>
Date: 04-10-2014 6:28 AM (GMT-05:00)
To content...@googlegroups.com
Subject Re: Question about content in UI strings

[Joe Pairman]

Rahel, I don't think that either the system you use to manage the strings or the formal roles of the people who review the strings are the most important things. There are two important things, in this order:

1. The process for creating and reviewing the strings, and the skill used in doing so. It takes knowledge and experience to create effective strings. Even more so if you'll be localizing the interface.
2. The technical ability to co-ordinate string updates across the resource files, the support / help content, and the glossaries that translators use. There are various ways to manage strings and pull them into / push them out of support content systems. I'd be wary of suggesting any specific best practice, as it depends on the individual organization. But I've seen it work well to have the software version control system used as the system of record, with automatic export of placeholder strings for UX copywriters to edit, and later export to XLIFF for translation. (Remember that there are specialized systems such as Passolo for string translation, so it may not make sense to use the exact same toolchain/workflow as you use for support content.) There's also the option to extract the strings automatically and populate content in a CCMS based on matched IDs, though it takes some co-ordination & investment to get this working smoothly.

Though I wrote this before reading Rick's answer, I agree with all his points.

Joe

[Rahel Anne Bailie]

The reason I am reluctant to have UX practitioners write the labels is because there is a definite risk that what a label gets called in the UI becomes disconnected from the sometimes thousands of help files, error messages, and so on. It can be disconcerting to search for the term used in a UI label and not be able to find out how to use a feature because it's called something else through all of the content. Not to mention that the translation processes usually come out of TC, and then you have to manage multiple sets of inconsistent terminology. Not to mention that UX people aren't wordsmiths (which is likely why Hide/Show is Hide/Unhide in one Microsoft product) and so while input from usability testing is important, why would UX be left to write the labels?

But the question to me wasn't about ownership, it was about whether you throw all the labels into a series of resource files (one for web, one for mobile, and then same thing for each language, etc), or do you manage them in some sort of CMS, or is there another way to do that. This is for enterprise accounting software, so massive amounts of help, training, support content, lots of screen and lots of labels.

---

Rahel Anne Bailie, Content Strategy / Content Management / Content Design
Intentional Design Inc. - Content strategies for business impact 
Co-producer: Content Strategy Workshops
Co-editor: The Language of Content Strategy - in stores now
Co-author: Content Strategy: Connecting the dots between business, brand, and benefits

[Rick Yagodich]

The who-writes-labels question is an important one. But should it really fall to those documenting the product to define the interface labels? I would say absolutely not. Best choice is a UX-wordsmith, as part of a testing team.

Your built-in assumption appears to be that the TC authoring tools don't contain the integration point to read the resource files. That is either a bad assumption, or an indication of a very poor state of affairs in TC. Whatever happens, whoever owns the labels, they should exist in some kind of agnostic storage (by which I mean I don't give a rip where they are, but everything needs to be able to read from them, and everything that does must not care where they are).

As to the actual form they are stored in… again, it is largely irrelevant. It can be a CCMS. It could just be resource files. The API that reads it into other systems will most likely pass back some form of XML or JSON.

Now, to the question of how to split the "files" in whatever storage… by delivery platform is an absolute no-no. If there is to be some distinction in labelling between web and mobile and whatever, then that is in which labels are injected to render that interface. Separate files will result in duplications and inconsistencies. If you have btn.submit, but for some reason want a different one on mobile, then you extend with btn.submit.mbl.

The need to split would be based on number of labels, and then your best option is by functional area.

 - R

[Rahel Anne Bailie]

On Thu, Apr 10, 2014 at 1:13 PM, Rick Yagodich <ri...@think-info.com> wrote:

>>The who-writes-labels question is an important one. But should it really fall to those documenting the product to define the interface labels? I would say absolutely not. Best choice is a UX-wordsmith, as part of a testing team.

It is an important question, but that is not my former client's situation. They don't have a UX-wordsmith. (As an aside, there are some UX people who make good wordsmiths, and others who suck at it. I wouldn't presume, for example, to be able to write labels in a foreign language, so if your UX person is ESL, then you have to rethink the wholesale assumption of who does what by job title.)

 

Your built-in assumption appears to be that the TC authoring tools don't contain the integration point to read the resource files.

No, I am not making that assumption. I said that is that is not my former client's situation.

 

That is either a bad assumption, or an indication of a very poor state of affairs in TC. Whatever happens, whoever owns the labels, they should exist in some kind of agnostic storage (by which I mean I don't give a rip where they are, but everything needs to be able to read from them, and everything that does must not care where they are).

So I think you may have missed the point of the original question. Someone asked me what best practices are because she is looking for research / information to take back to her organization to fix a pain point. It has nothing to do with anything I may or may not assume. You would be surprised at some of the Fortune 500 companies who have no concept of agnostic storage.

As to the actual form they are stored in… again, it is largely irrelevant. It can be a CCMS. It could just be resource files. The API that reads it into other systems will most likely pass back some form of XML or JSON.

Now, to the question of how to split the "files" in whatever storage… by delivery platform is an absolute no-no. If there is to be some distinction in labelling between web and mobile and whatever, then that is in which labels are injected to render that interface. Separate files will result in duplications and inconsistencies. If you have btn.submit, but for some reason want a different one on mobile, then you extend with btn.submit.mbl.

The need to split would be based on number of labels, and then your best option is by functional area.

I agree about where they are stored. I disagree that they can be [easily and effectively] maintained if they are stored in a silo, inaccessible to anyone except the "guy with the magic key" (and we all know organizations like that). It is a much better workflow to have the authoring aspect integrated with, or at least readily visible to, the people who need to maintain them, in context of the other work they are doing. Again, this is from my observation of authors in large companies who make notes and write emails and then tear out their hair when the updates don't happen because the person whose job it is to go into the file and make the changes won't do so.

But that's for another debate. Right now, I'm focusing on getting some progressive ideas to help out this contact.

Rahel

[Rick Yagodich]

Sorry Rahel

Clearly, there is some lack of clarity in this communication. I was
pretty sure I was answering the questions as you asked them. The best
practice is largely down to the technical implementation.

I have implemented the same model on several clients. Admittedly, it was
a closed web CMS system, so the reuse by tech comms is not a part of it.
But it is a system that works really well. None needed particular
version control either, so that extension would complicate things a bit.

a) There must be a "magic key" in the ability to create new label
instances. This is simply because a label created without a usage
scenario is meaningless. The process doesn't need to be limited per se,
but it is largely irrelevant for anyone except developers to do.

b) The creation of new label instances is itself content management /
configuration. Each new instance is created with a key-value, a type
(static text, number, translatable text, multi-element (e.g. selectable
values), etc), an initial value (placeholder for dev), and a verbose
description.

c) Anyone who has access permission to the relevant part of the CMS can
edit the labels. Who this should be is a question of governance. Though
it may sound nice to be able to publish single field changes
individually, that extra functionality is usually overkill.

c') Anyone with access to the "magic key" can edit the verbose description.

d) If translation is involved, manual translation of the localised
labels is discouraged, as these would be overwritten by the bulk
translation process. Also, for automated / agency translation, the
verbose description should be exported as metadata for the field, to
give the translator context.

e) Everything that makes reference to the label values should pull them
from this central location (or have them pushed).

Of course, all the above is then subject to the capabilities of their
system.

- R