We have often said that in Orion, a page is defined as "task + resource." We wish to follow a common page layout so that it's easy for the user to understand where to find the tasks they are interested in performing.

+

We have often said that in Orion, the work a user is doing on a particular page can be thought of as "task + resource." As we design more complicated pages, it has become important to formalize the anatomy of an Orion page, so that we can define a common page layout that lets the user work with the resource+task at hand, and use well known mechanisms to navigate to other resources within a task page, or choose related tasks.

−

= Page Anatomy (Old) in Orion 0.2/0.3 =

+

Our original work in Orion 0.2/0.3 [[/Page Layout 0.2|focused on designing a common header and footer]], but we didn't have a fully specified "anatomy." This left developers building individual pages to make a best guess as to where certain parts go that may not have been present in the pages already built.

−

In general, the top of the page contains links to other tasks and resources that you might wish to discover, and as you move down the page, the buttons and links become more focused on the task at hand. This all seems pretty obvious, but when organizing the page content it has been helpful to be explicit about this approach and to name these tasks and page elements.

+

−

In our early work in Orion, we used the following terms when talking about the page organization, from general to specific.

+

For Orion 0.4, we need to revisit the anatomy of our pages to ensure that we are consistent in showing various elements. We want to formally describe the elements on the page, with terminology that makes it easy to talk about this structure without necessarily referring to visual positions such as "header" or "footer."

−

*'''Branding''' isn't functional (though it may link to the home page) but establishes the brand.

+

−

*'''Discovery links''' appear prominently/consistently on the page and teach you what can you do. They may even link to other sites. They are the least related to what you are doing.

+

−

*'''Primary navigation links''' appear prominently/consistently and help you to search for things or go to common tasks. They may or may not be related to your current task. (The distinction between discovery and primary is not clear, but the main point is that discovery links are there to show you things you might not know you could do otherwise.)

+

−

*'''User info''' shows who you are and lets you manipulate your account, login, etc.

+

−

*'''Page title''' describes the kind of page/task you are on

+

−

*'''Where I am''' indicates where you are and perhaps has a breadcrumb to lead you elsewhere.

+

−

*'''Task Commands''' (links, tabs or buttons) help you manipulate the entire task/resource at hand, there might be multiple levels of task links depending on what the page is doing

+

−

*'''In-resource navigation''' can help you find your way within a large resource or change the view within that resource.

+

−

*'''Resource/edit commands''' (links, buttons, gestures, etc.) appear inside the main resource you are working with and help to edit/act on that resource

+

−

For Orion pages, then, if a page is generally "task + resource" then the visual on the page that orients you to what you are doing is a combination of "Page Title (task) + Where I Am (resource)." Note also, that this combination is typically shown in the browser tab so you can quickly find the thing you want to work on when it's already open.

+

== Problems with current page structure ==

−

+

−

+

−

== Other Site Examples ==

+

−

We originally looked at other developer sites for examples of how this kind of layout is done. Our main comparisons have been Github and Jazz. We've looked at github pages and attempted to label the page structure using our own terminology. Jazz has a [https://jazz.net/library/article/458/ rich, substantive style guide] describing page anatomy and where elements should appear. We have used this as a guide, while noting differences in design goals that would cause us to do something different.

+

−

+

−

=== Github (pre "skinny header") ===

+

−

Github's primary and discovery links were organized in two rows. The top row is mostly concerned with things related to your overall account, and the bottom row seems more discovery focused, combined with a search box. (A little upside down conceptually, but presumably the account links are given more prominence since they are more common.)

+

−

+

−

Tasks are organized in tabs. The layout as it relates to what you are doing is very structured/explicit, with the downside that there might be a lot of vertical space used before you get to the primary task at hand. (As of 12/2011, Github has introduced the [[https://github.com/blog/1007-skinny-header skinny header]] which is a lot more Orion-like in collapsing the header content vertically). Note there is not an explicit "page title" from a task point of view, just "Github."

Jazz is navigating across various products (called projects) as well as helping navigate the jazz community (blogs, etc.). The top set of menus/links could be considered the high level discovery links (similar to what github puts in the second row). A second "bar" of info combines the top level page title with the account related links on the right. A third level of links/tabs navigates the secondary tasks, and the search appears on the right (the search is scoped to this secondary level). All of this task navigation is in various blue colors, with the resource itself shown in white.

+

−

+

−

The top part of the resource includes more "where I am" (with breadcrumb) along with the tasks and navigation aids that act upon the whole resource. (Jazz calls this the Page Control & Resource Header Area.) Underneath, we can use tabs to pick a more specific view of the resource and then edit those aspects of the resource. Within the resource, gray bars are used to designate different parts of the resource, and commands/links related to those parts appear in the gray bar, to orient the task to the "section" of the resource.

+

−

+

−

Once again, this is very structured, with the downside of vertical space required to present the structure before you can actually work on the task.

+

−

+

−

[[Image:jazzworkitem.png]]

+

−

+

−

The browser tab uses "where I am + summary". [[Image:jazztab.png]] Note that there is no use of the primary task or page title "Rational Team Concert" or "Work Item". This can work because the name of the resource (Enhancement NNN, Work Item NNN, etc.) implies that you are using workitems.

+

−

+

−

== Orion 0.2/0.3 ==

+

−

In the initial designs for Orion, we wanted to honor a formal visual hierarchy structure, but we assigned high priority to constraining vertical space. We wanted to use significantly less pixels than Jazz or Github. One of the primary tasks in Orion is editing code, a task that is very deep and complex, where as much room is needed for the resource itself as possible. We considered whether we should have a special layout for the editor vs. the other pages, but decided to try to design a layout that would work for all pages.

+

−

+

−

One of the biggest changes from most website header layouts was to include information about "where I am" (the resource being edited) in the header. We thought we could constrain vertical space by using the breadcrumb to help navigate and show current location.

+

−

+

−

=== Editor ===

+

−

As you can see, the amount of vertical space used for the elements that do not belong to the resource/task at hand is about half that of the space used in jazz (112 vs. 245 pixels).

+

−

+

−

In the editor, you don't really see any links/buttons for "in-resource tasks" because most of the tasks involve editing or using keybindings to execute commands that don't appear on the dark toolbar or in the editor.

+

−

+

−

[[Image:editorlayout.png]]

+

−

+

−

=== Navigator ===

+

−

The navigator uses the same approach, but since the "resource" being manipulated is a list of files and folders, there are more commands inside the list.

+

−

+

−

[[Image:navlayout.png]]

+

−

+

−

=== Git ===

+

−

The git functionality came later in the release, and you can tell that things that perhaps should have been shown underneath the header started to get packed into the header, because we didn't have a formal information hierarchy or multiple dimensions of "where I am". In git, the "Where I Am" is more complicated, because it's not just important to know what resource is being viewed, but also what branch. So we start to get really crowded page headers. We also started to introduce pagination, and we didn't have an explicit place designated for the page navigation links.

+

−

+

−

[[Image:gitlog.png]]

+

−

+

−

The git status page is the first page to segment the resource/task into subviews. We did not have a clear/consistent strategy for using trim to delineate sections, or for associating commands that operate on a particular section with the content. (We don't have the equivalent of jazz's gray bars for separation, or of github's inner tab rows with commands)

+

−

+

−

[[Image:gitstatus.png]]

+

−

+

−

= Revisiting Page Anatomy in Orion 0.4 =

+

−

As seen above, we have outgrown our visual layout/anatomy. We need to revisit the terminology/elements on our pages and ensure that our pages are consistent in showing the various elements.

+

−

+

−

== Problems ==

+

* '''Header content.''' The header is too crowded for some views (that are trying to cram multiple levels of "where I am"), yet it is still considered too tall when editing or trying to work on a small screen/tablet device. We've just added a feature to hide the banner/footer when editing. We should consider using more vertical space to address the additional context information, since the user can get rid of it when needed. Perhaps the "where I am" and breadcrumb navigation should be placed below the header. This is more in line with what other sites do, and also means that if we collapse the header when editing, etc., some of the more useful bits currently in the header will still be visible in a secondary layer beneath the header.

* '''Header content.''' The header is too crowded for some views (that are trying to cram multiple levels of "where I am"), yet it is still considered too tall when editing or trying to work on a small screen/tablet device. We've just added a feature to hide the banner/footer when editing. We should consider using more vertical space to address the additional context information, since the user can get rid of it when needed. Perhaps the "where I am" and breadcrumb navigation should be placed below the header. This is more in line with what other sites do, and also means that if we collapse the header when editing, etc., some of the more useful bits currently in the header will still be visible in a secondary layer beneath the header.

* '''Footer content.''' The footer content was never designed with any structure in mind, and some of the elements that appear in the header could be moved to the footer.

* '''Footer content.''' The footer content was never designed with any structure in mind, and some of the elements that appear in the header could be moved to the footer.

Line 84:

Line 19:

* '''Page Navigation Commands.''' In 0.3, the page navigation commands appeared alongside the task commands. In the 0.4 stream, we've moved navigation commands to the right on the toolbar. It seems logical to separate these, but we should revisit the location in the context of the larger redesign.

* '''Page Navigation Commands.''' In 0.3, the page navigation commands appeared alongside the task commands. In the 0.4 stream, we've moved navigation commands to the right on the toolbar. It seems logical to separate these, but we should revisit the location in the context of the larger redesign.

−

== Page Elements ==

+

== Defining Page Elements ==

For Orion 0.4, we further expand on the page elements and introduce semantic elements (such as "Legalese") for info that we used to refer to visually ("the footer.")

For Orion 0.4, we further expand on the page elements and introduce semantic elements (such as "Legalese") for info that we used to refer to visually ("the footer.")

−

*'''Branding''' (top left corner)

+

*'''Branding''' (typically the top left corner)

*'''Legalese''' (usually in the footer)

*'''Legalese''' (usually in the footer)

*'''Discovery links''' appear prominently/consistently on the page to teach you what can you do. These links may even link to other sites. They are the least related to the task at hand, but you should know about them.

*'''Discovery links''' appear prominently/consistently on the page to teach you what can you do. These links may even link to other sites. They are the least related to the task at hand, but you should know about them.

−

*'''Incidental links''' appear less prominently, but still consistently, on the page. They are links to less important places, such as user guides, documentation, support info, etc. (usually in the footer)

+

*'''Expected links''' appear less prominently, but still consistently, on the page. They are links to less important places, such as user guides, documentation, support info, etc. The user expects them to be there, so is willing to go looking for them.

*'''User info''' shows who you are and lets you manipulate your Orion environment

*'''User info''' shows who you are and lets you manipulate your Orion environment

*'''Search''' the location of search may depend on whether it is scoped to the current page. It seems worthwhile to consider search a separate element rather than part of the primary navigation.

+

*'''Search''' the location of search may depend on whether it is scoped to the current page.

−

*'''Page title''' describes the kind of primary task you are on. It is static.

+

*'''Task''' (aka "Page Title") describes the user task you are on. It is static.

−

*'''Where I am''' indicates where you are. This needs to be broken down further. (Needs work.)

+

*'''Resource''' (aka "Where I Am") indicates what resource you are working with.

** '''Primary dimension''' (optional) defines the main context for viewing your resource. (Need a better name). For some resources, there may only be one dimension (such as the workspace) so there is no need to name/show it. However, once you introduce source control, which can populate your workspace, you have an added dimension, such as the git branch name. Part of showing primary location is allowing user to switch it. Also note that the dimension might be provided by a plug-in so it needs to be able to annotate other pages with the dimension switching.

** '''Primary dimension''' (optional) defines the main context for viewing your resource. (Need a better name). For some resources, there may only be one dimension (such as the workspace) so there is no need to name/show it. However, once you introduce source control, which can populate your workspace, you have an added dimension, such as the git branch name. Part of showing primary location is allowing user to switch it. Also note that the dimension might be provided by a plug-in so it needs to be able to annotate other pages with the dimension switching.

** '''Secondary dimension''' (optional) further refines the context if needed. For example, local/remote branches in git.

** '''Secondary dimension''' (optional) further refines the context if needed. For example, local/remote branches in git.

Line 116:

Line 51:

== Proposed Layout ==

== Proposed Layout ==

−

The following wireframe repositions the page elements by including all static information in a smaller top area, with task and resource information in a separate area below. The notifications are moved to the footer. This wireframe includes a full content area (the entire wireframe is 1024x768) for perspective. (For the rest of the pictures, we'll just show the header and resource part since the footer is the same.)

+

The following wireframe repositions the page elements by including all static information in a smaller top area, with task and resource information in a separate area below. The notifications are moved to the footer. This wireframe includes a full content area (the entire wireframe is 1024x768) for perspective.

−

+

[[Image:orionheaderwireframe.png]]

[[Image:orionheaderwireframe.png]]

−

Please note this is a color-coded wireframe, not a proposed style! It's not assumed that the things shown as boxes will in fact have borders or colored trim. The following example shows the header for an Orion editor using this new anatomy.

+

Please note this is a color-coded wireframe, not a proposed style! It's not assumed that the things shown as boxes will in fact have borders or colored trim.

+

=== Simple Pages (non-sectioned) ===

+

The following example shows the header for an Orion editor using this new anatomy. (This is the last wireframe that shows the whole screen. For the rest of the pictures, we'll just show the header and resource part since the footer is basically the same.)

[[Image:orioneditorwireframe.png]]

[[Image:orioneditorwireframe.png]]

Line 133:

Line 69:

[[Image:oriongitlogwireframe.png]]

[[Image:oriongitlogwireframe.png]]

+

=== Outliners ===

When the resource is large enough to require a dedicated outliner, a command toolbar is applied to each pane separately.

When the resource is large enough to require a dedicated outliner, a command toolbar is applied to each pane separately.

Line 140:

Line 77:

−

Here's the editor with an outliner.

+

=== Sections ===

−

+

−

+

−

[[Image:orioneditoroutlinerwireframe.png]]

+

−

+

Pages that have distinct "sections" include a command area (toolbar) with each section. There is no "global" toolbar since there is not a "default" section. Again, note that this is a wireframe and it's very likely the sections wouldn't actually have boxed headers. What's important is that we get common styling and conventions for the associated commands, etc.

Pages that have distinct "sections" include a command area (toolbar) with each section. There is no "global" toolbar since there is not a "default" section. Again, note that this is a wireframe and it's very likely the sections wouldn't actually have boxed headers. What's important is that we get common styling and conventions for the associated commands, etc.

Line 157:

Line 90:

[[Image:orionflatrepowireframe.png]]

[[Image:orionflatrepowireframe.png]]

+

=== Outliners with Sectional Pages ===

For pages with many sections, we expect that we'll need an outliner for navigating the sections. It remains to be seen whether the outliner would show only one section at a time (master/details pattern) or just navigate to the selected section. It's not clear that every page with "sections" should default to an outline view, we'll need to figure this out.

For pages with many sections, we expect that we'll need an outliner for navigating the sections. It remains to be seen whether the outliner would show only one section at a time (master/details pattern) or just navigate to the selected section. It's not clear that every page with "sections" should default to an outline view, we'll need to figure this out.

Line 162:

Line 96:

[[Image: orionsectionoutline.png]]

[[Image: orionsectionoutline.png]]

−

−

−

Here is the git repo page using the outline approach. (The user preferences page is probably a more likely example of a page needing outlined sections.

−

−

−

[[Image:orionflatrepowithoutline.png]]

Latest revision as of 15:32, 16 January 2012

We have often said that in Orion, the work a user is doing on a particular page can be thought of as "task + resource." As we design more complicated pages, it has become important to formalize the anatomy of an Orion page, so that we can define a common page layout that lets the user work with the resource+task at hand, and use well known mechanisms to navigate to other resources within a task page, or choose related tasks.

Our original work in Orion 0.2/0.3 focused on designing a common header and footer, but we didn't have a fully specified "anatomy." This left developers building individual pages to make a best guess as to where certain parts go that may not have been present in the pages already built.

For Orion 0.4, we need to revisit the anatomy of our pages to ensure that we are consistent in showing various elements. We want to formally describe the elements on the page, with terminology that makes it easy to talk about this structure without necessarily referring to visual positions such as "header" or "footer."

Contents

Problems with current page structure

Header content. The header is too crowded for some views (that are trying to cram multiple levels of "where I am"), yet it is still considered too tall when editing or trying to work on a small screen/tablet device. We've just added a feature to hide the banner/footer when editing. We should consider using more vertical space to address the additional context information, since the user can get rid of it when needed. Perhaps the "where I am" and breadcrumb navigation should be placed below the header. This is more in line with what other sites do, and also means that if we collapse the header when editing, etc., some of the more useful bits currently in the header will still be visible in a secondary layer beneath the header.

Footer content. The footer content was never designed with any structure in mind, and some of the elements that appear in the header could be moved to the footer.

Resource switching beyond the breadcrumb. We use the breadcrumb for scoping the information on the current page, but there are additional ways to look at the page data (for example, git branches and local/remote). We need multiple levels of "where I am/what I'm looking at" and a way to switch between these. Using "task commands" in the toolbar to accomplish this clutters things up. An early mockup tried to solve these problems in the current header anatomy and it does not seem sufficient. We also need a way for plug-ins to contribute contextual "where I am" information, such as being able to know in the editor which git branch the file came from. Bottom line is we probably need the header to be more static (it could even be smaller) and then the "where I am" moves just beneath.

Subsection affordances. The commands/links that appear for subsections of a page do not visually relate to the subsections, and it's not always clear which subsections belong together. Users have trouble orienting themselves in pages like "Git Status" and may not notice certain commands (such as push) because the affordances are not clear.

Links to related pages. In some workflows, it's very common to open a related page. For example, the "Git Status" page includes mini-logs and links to those logs. But one cannot get to "Git Status" from a "Git Log." We need to be specific about the relationship between pages and provide a place where the user can quickly access "related links." These links are different than discovery or primary nav links. Need to understand how this relates to favorites, and how favorites can be accessed from anywhere.

Page Navigation Commands. In 0.3, the page navigation commands appeared alongside the task commands. In the 0.4 stream, we've moved navigation commands to the right on the toolbar. It seems logical to separate these, but we should revisit the location in the context of the larger redesign.

Defining Page Elements

For Orion 0.4, we further expand on the page elements and introduce semantic elements (such as "Legalese") for info that we used to refer to visually ("the footer.")

Branding (typically the top left corner)

Legalese (usually in the footer)

Discovery links appear prominently/consistently on the page to teach you what can you do. These links may even link to other sites. They are the least related to the task at hand, but you should know about them.

Expected links appear less prominently, but still consistently, on the page. They are links to less important places, such as user guides, documentation, support info, etc. The user expects them to be there, so is willing to go looking for them.

User info shows who you are and lets you manipulate your Orion environment

Search the location of search may depend on whether it is scoped to the current page.

Task (aka "Page Title") describes the user task you are on. It is static.

Resource (aka "Where I Am") indicates what resource you are working with.

Primary dimension (optional) defines the main context for viewing your resource. (Need a better name). For some resources, there may only be one dimension (such as the workspace) so there is no need to name/show it. However, once you introduce source control, which can populate your workspace, you have an added dimension, such as the git branch name. Part of showing primary location is allowing user to switch it. Also note that the dimension might be provided by a plug-in so it needs to be able to annotate other pages with the dimension switching.

Secondary dimension (optional) further refines the context if needed. For example, local/remote branches in git.

Hierarchical location is shown in a breadcrumb. Once the primary/secondary dimensions are established, the breadcrumb is used to scope into the hierarchical content. This statement suggests that in something like a git page, the breadcrumb information should appear lower in the page than the branch and local/remote info. (This also seems to jive with the Jazz approach of putting the breadcrumb in the resource area). We also need to think about the breadcrumb in the editor. It does not do scoping, but rather takes you to the navigator. In other pages, it scopes the current list. We need to reconcile this. Perhaps we just define breadcrumb behavior for lists vs. single resources.

Resource Name is the "thing" that you are working with, having resolved the various dimensions and containment.

Related task links offer to take you to another page based on what you are currently doing.

Task+Resource Commands (links, tabs or buttons) help you manipulate the entire task/resource at hand. These are now specifically defined as commands that change the state of the resource and do not include commands that navigate, change the view, or the "where I am"

Resource View Controls

Pagination Navigation

View switching

View options

Outliners help to navigate through a large resource

Sections show different parts/aspects of the same resource/task that one may want to work with.

Resource/edit commands (links, buttons, gestures, etc.) appear inside the main resource or sections you are working with and help to edit/act on that resource

Note that this list captures the atomic semantic elements that will get combined into a visual area. For example, Jazz defines an area on a page called the "Page Control & Resource Header Area" which contains the "Where I Am," "Task Commands," "In-resource navigation," etc. The important thing is to establish the visual hierarchy and ensure that we have room for the various atomic elements. It's not clear that any one Orion page contains all of these elements, but we need to determine that when keeping room for them...

Proposed Layout

The following wireframe repositions the page elements by including all static information in a smaller top area, with task and resource information in a separate area below. The notifications are moved to the footer. This wireframe includes a full content area (the entire wireframe is 1024x768) for perspective.

Please note this is a color-coded wireframe, not a proposed style! It's not assumed that the things shown as boxes will in fact have borders or colored trim.

Simple Pages (non-sectioned)

The following example shows the header for an Orion editor using this new anatomy. (This is the last wireframe that shows the whole screen. For the rest of the pictures, we'll just show the header and resource part since the footer is basically the same.)

Here's an example of git log using the new header. Note that the branch and local/remote switching can now be done in the second section without a massive breadcrumb.

Outliners

When the resource is large enough to require a dedicated outliner, a command toolbar is applied to each pane separately.

Sections

Pages that have distinct "sections" include a command area (toolbar) with each section. There is no "global" toolbar since there is not a "default" section. Again, note that this is a wireframe and it's very likely the sections wouldn't actually have boxed headers. What's important is that we get common styling and conventions for the associated commands, etc.

Here is the "sectional" page wireframe applied to the new "flat style" repository page.

Outliners with Sectional Pages

For pages with many sections, we expect that we'll need an outliner for navigating the sections. It remains to be seen whether the outliner would show only one section at a time (master/details pattern) or just navigate to the selected section. It's not clear that every page with "sections" should default to an outline view, we'll need to figure this out.

Apart from doing the visual design (color, fonts, trim, etc.) for the header and the command sections, some other issues need to be determined:

What are the conventions for representing commands in the various scopes? Links, icons, buttons, etc.

command toolbar

section commands

item level commands

How does a navigation pane like "Favorites" fit into this model? Do we consider it the "super outliner"

How would you get to Favorites when you already have an outliner, does it "swap in?"