IBM Rational User Technologies guidelines website and content management system

As an intern for IBM, my primary responsibility was to evaluate and improve how the user experience and documentation group created, managed, and shared internal guidelines, or the information required for everyine to create consistent and high-quality work.

After interviewing fellow employees, evaluating the problems that people were having, and researching alternatives, I implemented a new content management system and designed and programmed a user-friendly website to help others quickly find the information that they need.


  • Organize and manage information about many different types of deliverables, from standard documentation to multimedia
  • Research, find, and implement a content management system that was easy and intuitive to use
  • Design and code a website that helps others find information quickly so they can continue with their tasks
  • Migrate the equivalent of thousands of pages of information from many different sources into a single content management system
  • Provide ongoing support for both content authors and consumers


  • Adobe Photoshop
  • Coda
  • jQuery
  • TextMate

User and methodical research

As always, if you don't understand users and their problems, you're not going to be able to help them. I dug right in with the following methods of research:

  • Interviewing dozens of fellow employees about their problems creating and consuming content that helps them or others complete their daily tasks;
  • Conducting open forums where others could discuss their grievances with the existing ways to create and discover useful content
  • Evaluating the existing tools available to create and display information
  • Exploring alternative tools to better create and display information

Developing requirements to solve existing problems

From my research, I developed the following requirements for any new methods for managing content.

Aggregate as much information as possible in a single place

Existing content was spread across a number of different websites, databases, wikis, and oft-forwarded emails in various levels of upkeep, which made it difficult to find information and evaluate its quality and relevance. To help others quickly find information, any new system would have to aggregate as much existing content as possible in one place.

There must be an effective search engine

Existing tools frequently let users down with, frankly, horrific search engines that often provided frustratingly irrelevant search results. Because users vastly preferred to use search engines instead of any other method of finding content, any new solution had to have a search engine that returned relevant results.

It must be as easy as possible to create and modify content

Authors wanted to be write content in a what-you-see-is-what-you-get manner and be able to immediately view their work.

If that sounds obvious, let me describe what people were dealing with: when I started, the primary tool for managing content, an Eclipse-based information center, required authoring content in one XML format and then committing it to source control before it would be transformed to HTML, compiled into an Eclipse plugin, added to the existing information center, and published the next day. This process was indicipherable to outsiders and frustratingly slow for those that even understood the process.

A wiki was neither acceptable nor desired

Although a wiki is a common answer for teams looking for a way to write and share internal content, for this team a wiki was not going to work. Previous wiki systems that the team had tried to use had severe performance and reliability issues; further, when the wikis were functioning, the large number of authors led to frustrating inconsistencies in content strategy and information architecture that made it difficult to find information. Eventually, you just didn't say "wiki" in polite company. This time, we wanted a site that anyone could access, but that only allowed a limited number of dedicated individuals to write. edit, and manage content.

Selecting ModX, a powerful and flexible content management system

After researching a number of alternatives, I recommended using ModX, an open-source content management application, to replace existing tools for managing content. ModX had the following advantages:

  • A web-based interface that allowed anyone to create content using only their browser – nothing more to install
  • All content is in a database, so all the information is in one place
  • Pages are organized and displayed in a hierarchy of folders, which was familiar to users and easy to understand
  • You write and edit content with a what-you-see-is-what-you-get editor, and updates are immediately visible and searchable
  • The templating system for displaying content is extremely flexible
  • You can control exactly who can create and modify content
  • The system has an active and supportive community of developers
  • It's free. Put another way: It's recession-friendly.

Migrating content to the new system

After a variety of stakeholders accepted my proposal, I migrated as much existing content as I could into the new system (through a variety of automated and manual methods) and then reorganized it all, combining information from many different sources into a task-focused hierarchy of information.

Here's a look at the ModX manager panel, which allows you to quickly create new content and edit existing pages.

An image of the content manager for the ModX system
click to embiggen
The interface to manage the site and its content

Designing and coding the front-end website

Because ModX has a very flexible templating system, I was able to present the date in whatever form I wanted, so I set out to design and code a website that focused on helping users quickly search for and find information.

Early wireframes

I designed and presented the following wireframes to stakeholders. My focus for the home page was a prominent search engine, and for content pages I wanted a to minimize clutter but also provide plenty of options for finding more information.

Wireframe for the home page
click to embiggen
Early wireframe for the home page
Wireframe for the home page, with additional notes and commentary on the image
click to embiggen
Wireframe for the home page, with some notes
Wireframe for a page to present a chunk of content
click to embiggen
Wireframe for a content page

First version of the site

After stakeholders approved the wireframes, I coded the site (using HTML, CSS, PHP, Javascript, and the template syntax for the system), staying very close to the wireframes.

Screen capture of the first version of the homepage for the revised site
click to embiggen
Revised site homepage, round 1
Screen capture of the first version of a content page for the revised site
click to embiggen
Revised site topic page, round 1

Not bad, but I can do better

Although I was fairly pleased with the improvements so far in content management and retrieval, a few months later I wanted to take another look at the design to create a more usable and professional-looking site.

I sketched out some ideas on a white board, set aside some time to code, and came out with an even better design.

Redesigned: a true information hub

Because no one gets it right the first time, the second version of the site was a significant improvement in appearance and usability. Click any of the images below to enter a slideshow with more information.

Screen capture of the second version of the home page for the site
click to embiggen
Homepage, round 2
Screen capture of some prominent buttons on the home page for the site
click to embiggen
Calls to action on the homepage
Screen capture of search results on the home page of the site
click to embiggen
Search results on the home page
Screen capture of a topic page for the site
click to embiggen
Revised design for the topic page
Screen capture of breadcrumb links that expand to show topics at the same level
click to embiggen
Enhanced breadcrumbs

This redesign received immediate praise. One coworker sent me this message:

Hi, Lee - just wanted to say that I was playing around with the 'new' guidelines site today. A huge improvement!

Ongoing support

Since the site has gone live, I've written a detailed user guide and I continue to maintain the site by responding to the occasional bug and teaching the occasional person how to work with the site. 

A vast improvement overall

The revised guidelines site has proven to be a useful and accessible information hub for the organization, providing a much better experience for authors to write and manage content, for administrators to manage the site, and for everyone to find the information that they need to complete their daily work.

Am I doing it wrong?

Comments? I don’t do open comments. Life is too short.

If you have something to say, get in touch via .(JavaScript must be enabled to view this email address) or on Twitter.