[wiki] TXP (written copy) Style Guide

gaekwad · 2011-07-19 08:52:22

1 capitalized -> capitalised

1 Texpattern -> Textpattern

Last edited by gaekwad (2011-07-19 12:22:11)

gaekwad · 2011-07-20 14:17:35

Hey Destry – something I just thought of while I was tidying up a wiki page…can you list what is permitted to be enclosed in a <code> tag?

I ask because I edited a reference to a Textpattern database table name (textpattern in this instance), and I made the decision that it looked more proper as a monospaced word…which in turn got me thinking: code examples are monospaced and styled differently to standard text, as are attribute values – but attributes themselves are not…so where do database terminologies fit?

Destry · 2011-07-21 08:51:40

gaekwad wrote:

9.1 Texpattern -> Textpattern

Zapped.

can you list what is permitted to be enclosed in a <code> tag?

Pete, you’re awesome! Way to get into it!

Off the top of my head, I don’t have an answer for the code issue, yet. But I’ve been thinking of another area too, which I’ll mention now before you beat me to it. :)

Btw, this is for the core devs attention as much as anybody…

The UI of Txp itself doesn’t have a style guide (that I’m aware of), which in turn makes it difficult to define guidelines in the Editorial Style Guide, which is necessary when talking about Txp’s UI, like in the Admin-side docs, for example. Without these two kinds of guides (one for devs and one for doc authors) working together, Txp’s UI and the user docs (wiki or elsewhere) will always be full of inconsistencies.

For example, let’s consider GNOME’s User Interface Style Guide, which is pretty good, and specifically the section on Text Labels, and specifically the section on Capitalizations. The focus of that section is how to use capitalizations in the UI of applications, so navigation elements; web form headers, legends, and labels; column headers, etc. If you look at their Table 8-3, it indicates how UI text elements need to be capitalized — as either Header style or Sentence style.

Compare that with just the top of Txp’s Admin > Basic preferences panel, where things are pretty good (assuming we like GNOME’s use of header vs. sentence) with exception of a few problems…

Menu items (which includes main navbar, drop-downs, etc.) are defined as header style, meaning every word is capitalized. So in the image above, “Visitor Logs” is correct, while “Switch role” (a plugin tab) is not. Another header issue is in the the Logging line where the shown drop-down option needs header style capitalization. Inversely, the other two field labels have header style when they should be sentence style. I’m sure there are a number of other problems too elsewhere in the admin-side.

You can see how this complicates user documentation efforts. Authors should be writing UI text elements as they are used in the UI, and if those text elements are wrong to begin with, they end up being wrong in documentation too.

I would propose that Txp starts a UI Style Guide of it’s own, which would be a boon for its professional appearance to the public. The guide wouldn’t have to be as extensive as GNOME’s (which is for complete OS), in fact another Google doc would probably work just fine, but it should cover everything that is relevant to Txp’s UI, and beginning with the text elements so that the editorial guide can be revised accordingly.

Which brings me back to the original aim of this post…

Guidelines for UI elements and code examples in the Ed. Style Guide

It’s one thing to know how to write them, as the UI Style Guide would make clear to authors (i.e., header vs. sentence style text elements), but we also need to know how to format those items in the editorial guide (user docs), and for things like the different text elements making up code examples.

I think we should look at what’s already done in this respect rather than reinvent the wheel. Don’t laugh, but Microsoft has done a lot of great work in this area. We could borrow some of their formatting rules to match up with Txp’s UI text elements and code. Or borrow from somewhere else, whatever, the point is we facilitate, not over deliberate and get things wrong in the end.

Anyone know of a source for formatting UI text elements, like Microsoft’s, but free? :)

Last edited by Destry (2011-07-21 09:38:14)

philwareham · 2011-07-21 09:06:04

@Destry

A UI style guide/design pattern is certainly something I’ll be looking into as part of the admin-area redesign for Textpattern 5. Been a bit busy of late with client work and also put the admin structure on hold whilst I finish the replacement front-side theme project.

It will be here at this Github page – probably looking at starting work on this in about a weeks time, deadlines permitting.

phiw13 · 2011-07-21 09:11:44

Destry wrote:

Anyone know of a source for formatting UI text elements, like Microsoft’s, but free? :)

Apple’s HIG is pretty good (see in particular Text Style Guidelines, as far as UI text-handling is concerned).

Fwiw, one of the best written user oriented documentation is the Camino user guide (I know, I’m biased… shht). Take a look at the source code as well, you’ll see things like <kbd class="menu">Bookmarks</kbd> (a menu item, sans-serif) or <kbd title="Command-K" class="shortcut">⌘K</kbd> (a keyboard shortcut, monospaced), and more.

Last edited by phiw13 (2011-07-21 09:12:38)

Destry · 2011-07-21 09:15:48

So, there’s already a need for a UI style guide beyond just documentation alone. In fact I know see four reasons for getting a UI style guide started:

To fix the inconsistencies that already exist in the Txp UI.
To aide user documentation.
To aide plugin developers (code and plugin docs)… the “Switch role” issue in the image above is case in point. :)
To aide new projects like what Mr. Wareham is working on. (And maybe some others coming up.) :)

Gocom · 2011-07-21 09:24:07

From the things you highlighted in the image, word “Textile” should be capitalized. It’s the name of the markup language, a proper noun and should always be written with capital “T”. Switch roles that on the other hand is a plugin tab.

Destry · 2011-07-21 09:27:20

@Gocom: Good catch on the proper nouns, you’re absolutely right.

I also found another error in the Logging line…the menu option that’s shown should have been every word capitalized (header style), per the GNOME example. I updated the image for that one.

The plugin tab I noted in my previous post. See item #3. :)

Ed. Image updated to reflect correction.

Last edited by Destry (2011-07-21 09:39:13)

Gocom · 2011-07-21 09:43:31

Destry wrote:

I also found another error in the Logging line…the menu option that’s shown should have been every word capitalized (header style), per the GNOME example. I updated the image for that one.

Please, no capitalizing of every word in the selectable option lists. I would highly prefer same rules as with sentences; first word capital, everything else lower if possible. Leave title case for headings and the menu tabs. Please do not use it for anything else.

Destry · 2011-07-21 09:45:55

phiw13 wrote:

Apple’s HIG is pretty good (see in particular Text Style Guidelines, as far as UI text-handling is concerned).

Thanks for the tip.

As far as a UI Style Guide goes, the dev-side of this community needs to make the call about what UI guides to establish and follow. Whether it’s based on GNOME’s or Apple’s or some other (it) doesn’t really matter to me. I just want to know what to follow in the Editorial Style Guide. Clearly something needs corrected before we can really get focused on the editorial side of things.

Fwiw, one of the best written user oriented documentation is the Camino user guide

I’ll have a look for sure.

Bloke · 2011-07-21 09:59:44

I personally loathe Capitalising Every Word — I prefer sentence case. When I added the Write tab stuff like Custom Fields and Article Image, I added them to the language server as Article image and Custom fields but there were complaints that it wasn’t consistent. Changing those isolated (new) cases was the path of least resistance but I’d prefer to go and do it properly one way or the other. Same with ‘Styles’ vs ‘Style’ on the Presentation tab. They’re just strings in the RPC server so simple to change once we have a chosen direction.

Plugins of course are a law unto themselves at the moment — probably due to a lack of style guide :-)

Last edited by Bloke (2011-07-21 10:00:38)

Destry · 2011-07-21 10:13:19

Let’s not beat around the bush: Textpattern User Interface Style Guide

Robert and Stef are document owners to do with it as they like.

I would be happy if the first section added to the guide address the use of text elements (e.g., capitalizations styles, and where used), as we’ve been talking about here (and let drop-downs be sentence case, obviously) so that I can sync the editorial guide with formatting examples that use UI elements correctly.

And, since there are inconsistencies in the current UI that need fixed (one way or the other), maybe a table in the UI guide would be good that shows the expected changes. It could (and should) be removed when actual UI changes have been made.

Last edited by Destry (2011-07-21 10:48:47)

Gocom · 2011-07-21 10:18:19

Bloke wrote:

I personally loathe Capitalising Every Word

I Feel Your Pain. I Do Too.

Same with ‘Styles’ vs ‘Style’ on the Presentation tab

It’s plural in some translations if that has any value. Other thing is the consistency across translations. For example in Finnish translation portion of the strings start with lowercase word, meaning that we have option lists with options that start lowercase while others use sentence case. But then again many of the translations outside English are pretty outdated.

The casing issues in Finnish are caused by the fact that the language strings are re-used in different places. When you make it correct elsewhere, it becomes incorrect somewhere else.

Last edited by Gocom (2011-07-21 10:22:47)

philwareham · 2011-07-21 10:34:40

I spoke with Robert a few weeks back and he seems quite happy to revise the language string file for TXP5 including making additions if needed.

philwareham · 2011-07-28 12:45:12

Was any decision made on whether to shorten “Textpattern CMS User Documentation”? Maybe to “Textpattern CMS Documentation” as at least it’s 5 characters shorter and surely all documentation is for user of some sort?

I’m going to open an issue for changing the wording for various parts of a default install (the What do you want to do next? article, external links and possibly the cateogories) to match your style guide where appropriate and just need a decision on the docs text.

Textpattern CMS

Textpattern CMS support forum

#31 2011-07-19 08:52:22

Re: [wiki] TXP (written copy) Style Guide

#32 2011-07-20 14:17:35

Re: [wiki] TXP (written copy) Style Guide

#33 2011-07-21 08:51:40

Re: [wiki] TXP (written copy) Style Guide

#34 2011-07-21 09:06:04

Re: [wiki] TXP (written copy) Style Guide

#35 2011-07-21 09:11:44

Re: [wiki] TXP (written copy) Style Guide

#36 2011-07-21 09:15:48

Re: [wiki] TXP (written copy) Style Guide

#37 2011-07-21 09:24:07

Re: [wiki] TXP (written copy) Style Guide

#38 2011-07-21 09:27:20

Re: [wiki] TXP (written copy) Style Guide

#39 2011-07-21 09:43:31

Re: [wiki] TXP (written copy) Style Guide

#40 2011-07-21 09:45:55

Re: [wiki] TXP (written copy) Style Guide

#41 2011-07-21 09:59:44

Re: [wiki] TXP (written copy) Style Guide

#42 2011-07-21 10:13:19

Re: [wiki] TXP (written copy) Style Guide

#43 2011-07-21 10:18:19

Re: [wiki] TXP (written copy) Style Guide

#44 2011-07-21 10:34:40

Re: [wiki] TXP (written copy) Style Guide

#45 2011-07-28 12:45:12

Re: [wiki] TXP (written copy) Style Guide

Board footer