Orion/Development principles

On this page, we collect our development principles - things that we believe are important to our success.

General

Speed trumps power - Given a choice between an implementation that is fast, and an implementation that is powerful, we should err on the side of being fast. Remember that speed is a feature too - if an application is perceived as fast, it is a joy to use, and if it is perceived as slow, it gets in the way of getting work done and may ever so subtly annoy the user. Keep the basic advice for response times in mind: Delays below 0.1 seconds for operation are good because the user will feel in control. Obviously, there are exceptions such as scrolling and entering text which has to be instantaneous. Between 0.1 seconds and 1 second is irritating delay that makes for an unpleasant experience, but does not interrupt the user's flow of thought. Anything over 10 seconds will drive users away. See http://www.useit.com/papers/responsetime.html.

Low barrier of entry for adopters - We don't want our adopters to have to buy-in to a lot of technologies before they can make use of what we've produced. Instead, we want to provide individual components and services that provide value //on their own//. In other words, we don't want to force people to have to re-write code just so that it fits into Orion, nor do we want them to have to re-write just so they can use one of our components. This means that external dependencies of components should be minimal, and the overall architecture should be modular, without making assumptions about how other components are implemented.

Reuse existing technologies - Don't re-invent the wheel if one already exists that we can integrate (through HTTP, or as open source that we consume), even if we could build a better wheel ourselves. We have limited resources and need to focus on those areas where we can provide the most value. We should invest in those technologies that we decide to use, where necessary. For example, instead of writing our own custom widgets, we should use existing widget toolkits such as Dojo, and contribute changes back to the widget toolkit if the widgets didn't quite fit our needs. The same principle applies to the server side, for example should we use, integrate, or work with an existing HTML validator, such as the W3C validator, instead of implementing HTML validation ourselves.

Remember the audience - We are using a powerful technique to ensure good usability: by self-hosting, i.e. using Orion itself to develop Orion, we create a tight feedback loop that makes us focus on the important things first. However, there is a risk that we think of ourselves as the only target users. We need to remember that not all users and adopters will be like ourselves. For example, it is important that we understand key workflows of our target audience (both end users and adopters!).

Modularity and API - Clearly defined and articulated component boundaries are what allows parts of an application to be reused in ways the component author never imagined. It will be a sign of success if consumers take our components and services and use them in wildly different applications. To do this, they need to be able to clearly see the available units of reuse, and be able to build their applications around these components with the expectation that they will continue to behave in the ways they expect. Good APIs also allow the implementation to evolve to meet unexpected future requirements, without breaking existing clients.

Client Side

Task focused - pages should contain appropriate information for the task being worked on, and only that information. It is easy to put more functionality on the pages later, if necessary, but it is hard to disentangle dependencies when you discover that a page is too heavy-weight and needs to be split.

Use native web capabilities - Use the browser native behaviour where possible. For example, we should not duplicate menu items that are in the browser's main menu, such as Cut/Copy/Paste, Zoom, Add Bookmark, etc - these should just work as expected. Links should be proper HTML links ("<a href=") instead of being JavaScript based, so that users can open them in a new tab or window as appropriate. We want the back button to work well, which means that important application state has to be encoded in the URL (before or after the hash). This will also allow bookmarking of pages.

Performant and lightweight - The main function of each page should be usable right away. We want to avoid having to display messages like "please wait while the application loads".

Minimal UI - The focus should be on the content ("give the pixels to the data") and the functionality. We want to keep our UI minimal-looking and neutral so that it can be styled and made more flashy later.

Design with mobile in mind - If a web page can be used on a mobile device, where you may have limited screen real estate, no keyboard, and touch instead of a mouse, it is still usable in a desktop browser. The opposite is not true. We don't have enough experience with this yet and thus shouldn't constrain ourselves too much, but we need to keep mobile in mind as one of the more important target devices for certain tasks. For example, browsing code, reviewing patches, or monitoring a build might make sense on a mobile device, but editing a lot of code probably doesn't.

Server Side

REST server API - The API for talking to services uses standard HTTP methods, headers, and response codes. GET and HEAD methods perform read-only functions (and are therefore cacheable). All non-POST methods are idempotent (repeating the same GET/PUT any number of times has the same effect and response, making the API robust over an unreliable connection). Relationships between server-side resources and services are expressed as links within the resources themselves, so the client never has to do URL construction or manipulation. The server maintains no session state (implicit in the principle that the browser back button and history should always work).

Neutral server technology - It should be possible to implement server services in JEE, but also PHP, .net, Ruby, Python, etc. Nothing in the server API assumes particular server technologies over straight HTTP and JSON as a request/response format. Support open authentication/authorization technologies (OpenID, OAuth, SSL, standard W3C validation, etc).