Textpattern Forum

You are not logged in. Register | Login | Help

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

gaekwad
Moderator
From: North Cornwall, UK
Registered: 2005-11-19
Posts: 1,168
Website

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

  1. 1 capitalized -> capitalised
  1. 1 Texpattern -> Textpattern

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

Offline

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

gaekwad
Moderator
From: North Cornwall, UK
Registered: 2005-11-19
Posts: 1,168
Website

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

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?

Offline

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

Destry
Moderator
From: Strasbourg, France
Registered: 2004-08-04
Posts: 2,365
Website

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

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)

Offline

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

philwareham
Core designer
From: Farnham, Surrey, UK
Registered: 2009-06-11
Posts: 1,623
Website

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

@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.

Offline

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

phiw13
Plugin Author
From: Japan
Registered: 2004-02-27
Posts: 613
Website

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

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)

Offline

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

Destry
Moderator
From: Strasbourg, France
Registered: 2004-08-04
Posts: 2,365
Website

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

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:

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

Offline

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

Gocom
Developer
Registered: 2006-07-14
Posts: 4,476
Website

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

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.


Rah-plugins | What? I’m a little confused… again :-) <txp:is_god />

Offline

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

Destry
Moderator
From: Strasbourg, France
Registered: 2004-08-04
Posts: 2,365
Website

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

@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)

Offline

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

Gocom
Developer
Registered: 2006-07-14
Posts: 4,476
Website

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

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.


Rah-plugins | What? I’m a little confused… again :-) <txp:is_god />

Offline

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

Destry
Moderator
From: Strasbourg, France
Registered: 2004-08-04
Posts: 2,365
Website

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

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.

Offline

Board footer

Powered by FluxBB