Monday, February 27, 2012

The Power of Semantics

Last month, I wrote about our attempts to build a semi-formal anatomy of Orion's common page elements. This anatomy seemed more important than focusing too strongly on a particular visual look or layouts. I also (somewhat optimistically) asserted that by the time we finish 0.4 you wouldn't have to think about this anatomy, but instead would simply think, "wow, these guys always get those links and buttons in just the place I expect them to be!"

So, how'd we do? Release 0.4 is done for all practical purposes. The M2 new and noteworthy gives a taste of what we've been up to lately, and the summary of all the 0.4 new and noteworthy should be out in a couple of days. I think it's important, though, to spend time thinking about some of our new features in terms of both "syntax" and "semantics."

In the web world, we all know about separation of styling (CSS) from the structure and content (HTML elements) on a page. But I'm talking about a distinction that goes beyond styling vs. structure. In the context of what's on a web page, I think of the styling and structure (layout, colors, fonts, buttons, graphics, words) as our syntax. The semantics are really the meaning behind that structure. Why do the various parts of the page appear where they do? How did we end up with those elements? Describing an additional level of semantics can help us not only design better pages, but provide function in ways we hadn't imagined before.

So I'd like to look at a few new Orion features in 0.4. For every screenshot of something new, I'd like to discuss not only the feature, but where we've made strides in the semantics behind it, and how this can help Orion get even better.

"New look" in the Orion page header

In Orion 0.4, you'll notice a new look. The header is divided into a skinnier common banner at the top and a taller page heading below.


From a presentation point of view, there are many things to notice. Some are simply stylistic changes, some represent a little more thought about the user tasks and workflows.

  • It's lighter and brighter than the previous gray, more contrast at the top.
  • Different fonts and colors than before.
  • The static part (logo, navigation links, user profile) is separated visually from the dynamic part (page title, breadcrumb, etc.)
  • The static part makes the header feel skinnier, while the dynamic part leaves more room for potentially lengthy content, such as a very long path name.


The items in the header are powered by a page anatomy. The idea here is that if a page can say a few things about itself to the common header code, the header can figure out how to present it in terms of a title, a breadcrumb, and a location. There is still work to do on the API side, but I think focusing on the structure of a page and how it influences the heading is laying the groundwork for future improvement. A page that can describe itself semantically can inherit interesting common function that goes beyond the presentation. For example, let's consider another feature in Orion 0.4 that is powered by the same idea.

"Related pages" menu

One of the usability goals for Orion 0.4 was to make it easier to move around within Orion. We wanted to identify the common workflows and make sure it's easy to move within or between pages to accomplish a task. So we've added a "Related pages" menu that gives you a handful of choices for other pages you might be interested in, based on what you are working with on the current page.


One reaction to this feature could be, "it's about time." What's so hard about adding a link on the editor page to "Git Status" when the file I'm editing is in a git repository? I suppose we could add features like this a little faster if we just added them rather than think about them in a generic sense. But if we know that from any Orion page, there is a handful of pages that the user will likely want to go to, isn't it nice that we can put them all in place? It's useful to think about the general case when designing a specific usability improvement. But even so, that's definitely in the "syntax" realm.


The semantics behind "Related pages" gets more interesting. It's one thing for a page to be able to list the links to pages of interest. However, Orion is an extensible system, and we don't want every page to have to consider what other pages might be around. So some semantics that allow a page to say what it is showing, and what other things it might care about, rather than just itemizing links of related pages, can let us build more interesting relationships between pages. For example, consider this "Related pages" menu from the Orion git repository page:

Here, the user is working in Orion with a git repository that is hosted at GitHub. So we figure out that one place the user might want to go is to that repository's GitHub page. This relationship can be determined because of some built-in semantics.

  • The page is able to call some common code that basically says, "hey, I'm a page that deals with repositories. Here's the URL I'm showing."
  • Another part of the code says, "I'd like to parse URLs and look for GitHub pages."
  • Finally, a related pages extension is used to establish that the "GitHub URL" command should be consulted when building the "Related pages" menu.
The way of expressing these relationships with API still needs work, but we have some pretty cool ideas of how we can make "Related pages" even more useful:
  • We could use the link scanner extension point so that any links built by the scanner in the Orion page content could also become candidates for "Related pages." For example, imagine a Bugzilla link showing up in the "Related pages" menu because you referred to a bug in your code.
  • We could develop a URL translating syntax so that plugins can more easily contribute mappings from page content to external links

Get Plugins

One of my favorite new features in Orion is the workflow for getting new plugins. Our community is growing, and more folks are writing interesting plugins. We currently don't have an "official" plugin catalog or store, but my teammate Mark MacDonald has been hosting a plugin listing on a page in his GitHub repository. We wanted to make this catalog more noticeable and reduce the steps needed to install a plug-in.


The link appears in the banner because the extension is used to specify a URL that should appear in the Orion banner. The links can refer to pages inside or outside of Orion. In this particular case, the link takes the user to Mark's catalog.

Nothing earth-shattering here, but suppose we click on one of these Install links. The link takes us back to Orion, ready to install the plugin we clicked.

If you aren't paying close attention while you click these links, you might simply think that our plugin catalog didn't catch up to the new look for Orion. But the reality is that this workflow took the user out of Orion to a third-party plugin catalog, and links from that catalog were able to bring the user back into Orion at the correct page, with the correct information filled in for installing a plugin. The reason this is one of my favorite new features in Orion is that we were able to add this at the end of the 0.4 release cycle without inventing any new generic constructs.


The semantics that allow this scenario to work have been covered in my previous blog posts, but it's kind of cool to review how they all play together in this workflow.

  • Our simple extension adds a link to the catalog. This extension has not been very interesting in the past because using it to link outside of Orion doesn't really enhance Orion's workflows, it just lets the user go somewhere else of interest. Kind of an "in-banner" bookmark.
  • We now provide a way for commands to describe the parameters they need so that common code can gather the information from the user. So the command for installing a plugin can now declare that it needs a URL from the user, rather than collecting it itself.
  • We now allow pages to define URL bindings. These bindings let a page establish a relationship between a token appearing in the page URL and a parameter needed by a command. That means the URL needed by the command that installs plugins can now be specified in the install page URL. So a catalog can link back to the Orion plugins page and fill in the URL that the user selected in the catalog.

Where do we go from here?

We are already talking about our goals for Orion 0.5. While there will be many priorities and features to plan, I can imagine a lot of workflow improvements we can make by continuing to focus on the semantic definition of a page.

  • We can make it simpler for a page to describe itself to the common code.
  • We can add more detail about the resource a page is manipulating. This includes defining resource dimensions that will give further control to the user for populating the page content.
  • A flexible URL translation syntax could let plugins easily describe mappings between a page's resource metadata and links to other places.
  • If we package the common header code to be more consumable, it's possible that a page like Mark's plugin catalog could consume the common header and thus more easily link back to Orion from the header and "Related pages" rather than have to know specifically how to get back to Orion.
I won't make bold predictions this early for Orion 0.5. But in my continuing pursuit of thinking about semantics so that you don't have to...I predict that our work in formalizing page semantics will pay off in workflows that let users cross in and out of Orion without even realizing it.


  1. Your good knowledge and kindness in playing with all the pieces were very useful. I don’t know what I would have done if I had not encountered such a step like this.

    Big Data Hadoop Training In Chennai | Big Data Hadoop Training In anna nagar | Big Data Hadoop Training In omr | Big Data Hadoop Training In porur | Big Data Hadoop Training In tambaram | Big Data Hadoop Training In velachery

  2. Its a wonderful post and very helpful, thanks for all this information. You are including better information regarding this topic in an effective way. T hank you so much.

    Dot Net Training in Chennai | Dot Net Training in anna nagar | Dot Net Training in omr | Dot Net Training in porur | Dot Net Training in tambaram | Dot Net Training in velachery