View
 

Language styleguide

Page history last edited by shb 14 years, 7 months ago

NOTE: These are all early recommendations and we welcome your input. Current pages (unfortunately) do not follow these guidelines and are inconsistent. We'll update all pages once this is nailed down.

 

 

Writing style

 

Short, declarative sentences with a crisp, active voice directed at the designer or developer who will be using our tools. View Apple's interface guidelines for a good example of the tone we'd like to follow in this wiki. Try to cross-link related plugins whenever possible.

 

 

Project name

The project name should always be written 'jQuery UI', never just 'UI'. Also we never expand to the full-length jQuery User Interface. Finally, no other forms (whether abbreviations, hyphenations, or capitaliztion) should be used, such as: JQUI, jQui, jquery.ui, jQuery.UI, jQuery-UI, jQuery UI Library, jQuery UI Framework, etc. Sentences like "Use the jQuery UI framework to get the job done" can be easily rewritten to "Use jQuery UI, the rich jQuery powered UI framework, to get the job done". This helps to focus on the branding.

 

 

Capitalization

 

Plugins should be named as briefly and unambiguously as possible and in the singular. Ideally, these should be a single word like "tree" or "sortable" but for longer names, we should separate words with spaces which is different than the current jQuery system. For example, we use "Progressbar" in the current documentation but "progress bar" is probably a more common way to write this. In a quick Google search, you find 3.5M results for "progressbar" and  12.3M results for "progress bar". This trend is consistent across all widget searches so it seems to be a better way to name components.

 

There are exceptions where the use of the singular for plugin names is insufficient. If the term in singular isn't applicable for the widget, the plural has to be used instead. A good example is the "tabs" plugin. Since instantiating a single tab would not highlight the plugin itself and is useless, "tab" does not describe semantically what the plugin does.

 

NOTE: this is a potentially big decision that could have ripples beyond this wiki so we need to discuss.

 

Plugin, page and section titles all use sentence capitalization. Only the first word is capitalized in a title, not each word.

Ex. "Language styleguide", not "Language Styleguide".

 

You can use spaces in wiki page titles -- these will appear in the URL as a "+" separator.

Ex. This page's URL is "http://jqueryui.pbwiki.com/Language+styleguide".

 

In the running text, plugins should be written in lower case with spaces.

Ex. "a select box is used...", not "a Select Box is used...".

 

 

 

Common terms

 

plugin - any jQuery widget or component

widget - a plugin that is a complete UI element that a user would interact with like a tab strip or calendar and will be styled in ThemeRoller

effect - a plugin that provides a visual effect like animation and easing       

interaction - a plugin that adds user interaction behavior to an element like draggable or resizable

utility - a plugin that adds a low-level capability or tool to the library like positioning or collision detection

 

 

 

Comments (2)

Richard D. Worth said

at 2:27 pm on Nov 20, 2008

Also, I prefer the single word all lower-case we currently use Ex. progressbar instead of Progress Bar or progress bar. But maybe it depends on whether you're talking about the specific jQuery UI control (progressbar) or a progress bar in general? To me the name of the control should be progressbar.

Todd Parker said

at 12:38 pm on Nov 24, 2008

I just changed "plug-in" to plugin here. Please try to fix these elsewhere. On the topic of naming in general, I'm ok with using singel wrds like you do now as much as possible so this matches what's already out in the world.

This bigger issue we need to deal with is the difference between how we call things here for the purposes of planning and coding vs. how they may be consumed in the outside world. For example:

We're releasing the "Progressbar" plugin in rc3. In the wiki, this is a small part of the larger set of "Progress indicators" that includes determinate/indeterminate types in both bar and circular styles. Do we keep a single "Progress indicators" page with all the sub-types listed as have now or break these into pages the match the final plug-ins? Will the indeterminate bar be a future option of the determinate bar like Apple handles it (the current value is ignored I guess) or will this be a new plugin called "Indeterminateprogressbar" which would mean we should re-name "Progressbar" to "Determinateprogressbar" (yuck). Where would the circular ones fit into this world? We can handle each one as a separate plugin, group them by type (determinate/indeterminate) with shape as a secondary option under each or group them by shape (bar vs. circular) with type (determinate/indeterminate) as a secondary option under each.

You don't have permission to comment on this page.