UI elements (labels, headers, menu items...)

Destry · 2012-05-15 08:05:35

As we work on quality project content (to the best of our abilities, under prevailing conditions), and develop guidelines (etc) to help ensure existing and new content (docs, magazine articles, UI elements…) is produced with some consistency to good conventions, it helps a great deal if the actual admin-side of the product in question (Txp) is consistent so that guidelines are in sync.

As one example…

I’m editing draft articles for the next issue of the magazine. Certain articles, such as tutorials, require using references to menu paths and other admin-side descriptions. For those that don’t know, there are industry-wide guidelines for styling UI text elements in copy; e.g., the Microsoft Manual of Style has been around for a couple decades at least. For Textpattern-related content, we’ve adopted the excellent Yahoo Style Guide (YSG) as the default point of reference—which was developed specifically for online content—and write our own guidelines only when we need a rule better-suited to the nature of this project (or the context of a given platform; e.g., wiki vs. magazine).

To the point, when we style menu paths, for example, we use the two main YSG guidelines for styling UI elements:

Write the elements exactly as they appear in the UI.
Make the elements bold to set them apart from regular text.

So we could have something like this: “Go to Extensions > Bio config and do your duty.”

So far, so good.

There’s another guideline for writing UI elements, which is practically universal in the digital world…

Use sentence-case convention for all titles, headers, labels, menu items, etc.

Sentence-case means the first word is capitalised and everything else is lower-case, excepting the usual norms for proper nouns, acronyms, etc. This is generally much better than capitalising every word (like you might see in novels) because web copy often requires titles/headings ending with punctuation, like a question mark (?). By using sentence-case we ensure all UI elements have the same structure whether ending with punctuation or not.

Here’s the problematic climax (you probably see it coming). The text elements in the Txp admin-side are not consistently sentence-case—neither the core text elements, nor text elements being added by plugin developers. It just seems to be a mix of whatever strikes people (this is an old issue, in fact, that still doesn’t seem to be resolved).

This screenshot shows the inconsistency with the core elements themselves, in panel labels (thus navigation), preferences, and menu items…

And this one shows an example with some extension elements…

As an editor of project content, it’s difficult for me to instruct writers (or write style guidelines they can respect) if the system itself has no consistency to work from.

The solution is easy:

Fix the core UI elements so that everything is sentence-case.
Make headway on the development style guide (that’s a core dev job), and make one of the guidelines requiring plugin developers using sentence-case too.

If everything related to the project (concerning UI elements) is sentence-case, then everything sings together in sweet harmony and we look like we know what we’re doing. At least in one respect.

Side: In the second image above, you see “smd Tags”. I’m guessing this was named thus because it’s a tricky menu item to name by itself. I.e., just using “Tags” is misleading, and “smd” is usually lower-case by convention, so what does a plugin dev do? In this case I would stick to conventions:

Leave the plugin prefix lower-case (sticking to the prefix name convention).
Then adopt the UI element convention of sentence-case.

So in that example the best use would be smd tags, if a better name couldn’t be produced. For example: “Go to Extensions > smd tags, and add your dope.”

philwareham · 2012-05-15 09:11:40

Huh? I’ve already sentenced capitalised all the text strings in Textpattern US English and International English, did it about a month ago. Are you using the latest language update?

Regarding UI elements, design patterns, whatever. I’m working on some BIG changes to that. Look out for major additions to SVN in the coming weeks.

Destry · 2012-05-15 09:24:22

Thanks, Phil. That did correct the core (and I have a mistake in my first image, as “Textile” is a proper noun to be capitalised, so actually okay). Nice job!

That just leaves plug developer additions to fix… Quelle bataille !

Regarding UI elements, design patterns, whatever. I’m working on some BIG changes to that. Look out for major additions to SVN in the coming weeks.

I’m just referring to how stuff is written and styled, which shouldn’t change anything, but I’m looking forward to whatever semantic improvements you make nonetheless.

Last edited by Destry (2012-05-15 09:27:17)

Bloke · 2012-05-15 09:26:42

Phil beat me to it but yes. Update your Preferences->Languages and you should see everything fixed up (in en-gb at least, maybe en-us too?)

Regarding “smd Tags” yes that was my exact dilemma. ‘Tags’ was too generic (and what if someone else wrote a tags plugin?); ‘smd_tags’ looked unfriendly; capitalizing (or all-capsing) my prefix looked weird, but not capitalizing the word ‘Tags’ made it look like the tab was a ‘mistake’ rather than by design, because all tabs around it had sentence case or first-word-caps case. Suggestions welcome.

EDIT: Perhaps Tags (smd) ?

Last edited by Bloke (2012-05-15 09:30:12)

Destry · 2012-05-15 09:41:04

Bloke wrote:

Suggestions welcome.

Already given. I think following the conventions in the order indicated is the safest way to go. Anything else is just a subjective hack that leads to individuals inventing it differently every time.

As long as the rule is noted in the style guide, then it’s legit.

For example, a golden guideline for plugin devs in the DSG…

==

If you can’t think of a clear/logical name for your plugin extension menu item, use your developer prefix on it, then treat the menu item with the standard conventions in the following order:

Always leave the prefix lower-case, regardless if it’s the first word.
Use sentence-case on the menu item otherwise, meaning everything else is lower-case if not a proper noun or abbreviation.

Correct → smd tags

Wrong → Smd tags
Wrong → smd Tags

===

Something like that.

Gocom · 2012-05-15 09:45:29

Bloke wrote:

EDIT: Perhaps Tags (smd) ?

of; Tags of Smd, Bloke of Tags, Tags of Bloke, Stef of the Tag
as verb, noun; Tag Stef, Stef Tags, Tag the Smd, Smd Tags
possessive; Smd’s Tags, Stef’s Tags
Giving it a (unique) name;
- Tag o’ Willa
- Tag Book
- Tagpattern
- Tag Tool

Destry · 2012-05-15 11:12:28

Bloke wrote:

Perhaps Tags (smd) ?

One obvious problem with words like “tags”, “forms”, “pages”, etc is they are easily confused between Txp semantical items (building blocks) and what most people already know them as in different contexts. And this is especially tricky in the wiki documentation where you have at least three different ways of using them:

As UI element labels (panel labels), which would follow the conventions noted earlier (e.g., Pages).
As wiki page links; different because we don’t link and make them bold (e.g., Pages) | [NTS: Oh, look, the wiki UI paths are not styled correctly there (me).]
When used not as a building block (e.g., in reference to a general web page).

So the use of “Tags” in the UI for anything other than meaning Txp’s Tags (and note we capitalize Tags as a semantical element in documentation) is undoubtedly confusing.

Looking at Jukka’s examples, where he has capitalized each word, it’s probably worth pointing out that capitalizing a proper noun in a label is not the same thing as the label being a proper noun. There’s an order of trump that still needs respected. I.e., we know that these are extension names, and by that fact alone they are capitalized. But we are talking about a UI in this case, and the extensions are serving as a list of UI menu items. Even though they are names, they still abide by the UI guidelines in the order required:

All developer prefixes are lower-case, even if first word.
Then apply sentence-case to the item (unless a word is a proper noun or acronym).

So if we have extensions: User Manager, Bio Config, Date Picker by Doug, The Textile Tool… these would accurately be coded as:

User manager
Bio config
Date picker by Doug
The Textile tool

The extension names themselves don’t retain original capitalisations, but the proper nouns that are part of the extension names do.

Gocom · 2012-05-15 11:17:37

Um, previously the suggestion was to use title case in navigation elements, wasn’t it? Or are we going to run around like headless chickens? I already updated all labels to title case, now I’m supposed to revert that. That’s great, isn’t it. Can I punch someone?

All developer prefixes are lower-case, even if first word.

Prefixes can be proper nouns, e.g. product/brand names. I write Rah with capital R when used a word, as it’s a proper noun. It’s also the plugin’s prefix.

Last edited by Gocom (2012-05-15 11:25:54)

Destry · 2012-05-15 11:34:14

That’s indeed frustrating.

I’m not aware of any guidelines for plugin developers (none that I’ve seen with thine own eyes), but as far as I know the core UI text has been sentence-case for a long time—for the reason that many elements, like preferences, end with punctuation, and so sentence-case is more consistent across the board. That’s certainly how Phil has updated things, anyway.

As far as it would concern me (which is a fair amount considering I’m vested in getting this right/steady in copy and editorial style guides), it would be recorded as sentence-case and never change again. But that’s just me.

Bloke · 2012-05-15 11:36:48

Destry wrote:

the use of “Tags” in the UI for anything other than meaning Txp’s Tags… is undoubtedly confusing.

You should try documenting it! “Using the <txp:smd_if_tag> tag…” myeeaaarh.

Maybe it should be renamed smd_all_type_structured_taxonomy or something so I can refer to it as AT-ST in the UI and give all the Star Wars geeks a boner :-p

@Jukka: let’s be thankful that rah_chuck_norris doesn’t have an admin tab. Anyone who sees “Chuck Norris” in their UI might be forgiven for thinking that clicking it will result in getting their face kicked in!

philwareham · 2012-05-15 11:38:28

You can punch me, I made the decision to sentence capitalise the whole admin side and was allowed to do it. But there were reasons for that – we had inconsistencies before with some stuff as sentence capitals and others as word capitals. Destry had also written a comprehensive documentation guidelines which advocated the former. It’s also the correct English grammar. Finally, it just looks better too IMHO.

Be reassured though that this is now the standard we will stick to – it won’t change again. I’ll put that info into the design patterns document when Txp4.5 is nearer completion.

Last edited by philwareham (2012-05-15 11:42:07)

Gocom · 2012-05-15 11:39:55

Done on rah apartment. Updated development versions of all public plugins to use sentence case labels. Rah_post_versions is now known by simply Versions and rah_change_passwords goes by Change passwords. Those are two only rah prefixed plugins affected, rest are either dropped (rah_autogrowing_textarea) and don’t get new updates, DIA/WIP or have only one word.

Bloke wrote:

@Jukka: let’s be thankful that rah_chuck_norris doesn’t have an admin tab. Anyone who sees “Chuck Norris” in their UI might be forgiven for thinking that clicking it will result in getting their face kicked in!

I will kick that to oblivion eventually, or at least hide it to some Old and useless category ;-) If and when I get some updates done.

Last edited by Gocom (2012-05-15 11:45:13)

Textpattern CMS

Textpattern CMS support forum

#1 2012-05-15 08:05:35

UI elements (labels, headers, menu items...)

#2 2012-05-15 09:11:40

Re: UI elements (labels, headers, menu items...)

#3 2012-05-15 09:24:22

Re: UI elements (labels, headers, menu items...)

#4 2012-05-15 09:26:42

Re: UI elements (labels, headers, menu items...)

#5 2012-05-15 09:41:04

Re: UI elements (labels, headers, menu items...)

#6 2012-05-15 09:45:29

Re: UI elements (labels, headers, menu items...)

#7 2012-05-15 11:12:28

Re: UI elements (labels, headers, menu items...)

#8 2012-05-15 11:17:37

Re: UI elements (labels, headers, menu items...)

#9 2012-05-15 11:34:14

Re: UI elements (labels, headers, menu items...)

#10 2012-05-15 11:36:48

Re: UI elements (labels, headers, menu items...)

#11 2012-05-15 11:38:28

Re: UI elements (labels, headers, menu items...)

#12 2012-05-15 11:39:55

Re: UI elements (labels, headers, menu items...)

Board footer