Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#25 2011-07-01 20:08:33

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

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

gaekwad wrote:

Google Search Engine Optimisation Starter Guide (PDF, free download).

Great resource. Thanks! I’ll give it a read when I have more time.

As for moving the style guide to the wiki, I could, and eventually might, but I don’t think it’s pressing. It started as a Goog doc a while ago because I have a personal Textpattern folder on Goog docs with other things-in-progress and it was just convenient for me to have everything in one place. And frankly, it’s a lot easier to write there than in Mediawiki (not that MW is hard, but Goog docs are just easier). Even if I do move it, I’d still keep the page locked. I’d rather people worked on the documentation, not the guides. :)

Btw, all. I’m heading out for a week with the Family starting tomorrow, so it’s likely to be radio silence (starting now) for me until a week from Monday. Over and out.

Offline

#26 2011-07-04 09:10:17

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,134
GitHub

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

  1. 4 in the style guide: I know it’s unlikely for how-to documentation, but the use of exclamation marks in code and shell scripts is a notable exclusion to this, so maybe add something in about that for completeness.

Also, something is needed re: the use of apostrophes. There will likely be a bunch of apostrophes used in the documentation wiki already, including U+0027 (typewriter apostrophe: ') and U+2019 (punctuation apostrophe: ’), and sticking to the one which is most widely rendered or most readily accepted when copying and pasting into Textpattern would be preferred.

Offline

#27 2011-07-18 11:55:21

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

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

Pete – Those are good thoughts, especially the one on quotes. I’ll work them in.

Offline

#28 2011-07-18 12:06:57

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

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

See the newly added “Please keep in mind…” paragraph in the head post.

I think what’s happening is we’ll need to add a section to the style guide that’s focused on the Tag Reference specifically, that way it can address the code-related ideas without clogging up the writing areas unnecessarily.

Last edited by Destry (2011-07-18 12:14:41)

Offline

#29 2011-07-19 08:10:36

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,134
GitHub

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

Destry – some more very minor things for completeness on your Google Doc:
i) add hyperlinks to the 2x URLs in the opening paragraph
ii) Textpattern gains and loses inverted commas over the first few pararaphs – looks a bit odd
iii) #7.6 behavior -> behaviour

Offline

#30 2011-07-19 08:40:10

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

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

Good eyes. Thanks, Pete.

I found a preference in Google doc that turns off smart quotes. I did that and changed all curly quotes (inverted or otherwise) to straight quotes. I think that will work going forward.

Offline

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

gaekwad
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,134
GitHub

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
Server grease monkey
From: People's Republic of Cornwall
Registered: 2005-11-19
Posts: 4,134
GitHub

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
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
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: Haslemere, Surrey, UK
Registered: 2009-06-11
Posts: 3,564
Website GitHub Mastodon

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: 3,058
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)


Where is that emoji for a solar powered submarine when you need it ?
Sand space – admin theme for Textpattern

Offline

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

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
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

Board footer

Powered by FluxBB