with Lorelle and Brent VanFossen

WordPress Codex Has a New Look

The WordPress Codex has a new look. Not a complete change, but a good start towards a new and more efficient online manual for WordPress users.

Since it’s conception over a year ago, developers wanted to provide a quality documentation site for the anticipated release of WordPress version 1.5. Between the WordPress developers and some awesome volunteers, they came up with the concept of the WordPress Codex. Codex is a “book formed of bound leaves of paper or parchment”, a name worthy of WordPress, coming from the idea of “words” and “printing presses”.

Volunteers began contributing articles, tips, and information and gathering information from the old WordPress wiki and from answers on the WordPress Support Forums, and slowly the Codex started to expand.

At first, all links to articles were added to the front, then they were broken down into categories, and then the first design for the front page look came into being, a group of boxes forming two columns down the front page.

This was an interesting and classy look to begin with, when there were only a few links to articles within the Codex. As the documentation grew, so did the links. As more documents came in, more categories were developed to encompass them. Soon the front page became littered with links and the boxes lost their charm. It became harder to read and more difficult to find the information the users needed.

It was now time to really start thinking about the audience.

Identifying Users

The WordPress Codex documentation team of volunteers started talking about how users “use” the Codex. A few things became clear.

  • They want the information now.
  • They don’t want to hunt for the information.
  • The majority of WordPress users are at the beginner to intermediate level.

In order to get the information they need, as fast as possible, we needed a look that would be easy to use, and to structure the information to match ability.

Getting Started With WordPress
The Getting Started section became the starting place. Here, the documents involved in installation and upgrading, the documents for getting started, would all be kept together. We broke down the information more to match beginner information with beginners, and then specific features for more experienced users.
Working With WordPress
The Working With WordPress section became the hands-on area, with information about the day-to-day process of using WordPress’s functions and features. We introduce the concept of plugins, administration issues like author and user levels, permalinks, comment spam, and website development issues.
Design and Layout
With WordPress version 1.5, having more control over a WordPress site became very important with the introduction of Themes. While applying a Theme to a WordPress site takes only a few clicks, customizing the theme to the user’s needs and imagination becomes more complex, introducing concepts and tools that are new to them. We broke this section into expertise levels, too, highlighting information for the beginner new to CSS, HTML, and PHP.
Advanced Topics
The Advanced Topics provided more comprehensive and intermediate level topics for the more experienced user, giving them the tools and information they need to handle the more challenging aspects of WordPress like customizing WordPress templates and template tags, customizing feeds, learning more about plugins and how to use and create them, and how to learn more about the WordPress database.
While WordPress is amazingly easy to use, people run into problems and can find many of the solutions in this section, from troubleshooting installations, dealing with comment spam, design and layout, and how to find more help about WordPress issues.
Development Documentation
With so many people now involved in helping WordPress, as open source code, evolve, documentation for the programmers needed a good repository, and we provided one here. It helps those very experienced users familiar with the inner workings of PHP, MySQL, and programming languages learn more about how WordPress works and what they can do to help.
About WordPress and Announcements
What also became clear is that the majority of WordPress users who visit the Codex have already made up their minds about using WordPress. A lot of them are convinced by friends and family, or it came installed on their server site. The About WordPress section was important to WordPress, but not to the users. Same for the Announcements. They are important to those who volunteer their time within the WordPress Community, but not to the people who visit the WordPress Codex to get help, and that’s the most important purpose of the site.

We now had an order for the front page, based upon user needs.

  • Getting Started With WordPress
  • Working With WordPress
  • Design and Layout
  • Advanced Topics
  • Troubleshooting
  • Development
  • About WordPress
  • Announcements

Finding the Codex Look

The WordPress Codex Volunteers working on this project visited a lot of wikis, many done with the software the WordPress Codex uses, Mediawiki. For the most part, while they come in different colors and a few different looks, many of these are cluttered and packed with massive links and boxes of information. WordPress’ is growing into a very clean site in general and we wanted to keep the clean, low key, look in the Codex.

After all, it’s about the information not the look that is important, and we wanted to keep the look as clean and easy to read as possible.

Carthik, one of the senior documentation team members, talked about making the Codex like a book, an online manual that would guide a user through the process, rather than a jumble of links to information. That triggered the inspiration for creating a clean table of contents look for the Codex.

Basically, we had the main sections, we just needed to help people get to the right subsection of those sections. For instance, if you want to change the design and layout of your WordPress Theme, and you only want information about changing your Theme and Template files, one click will take you to a collection of articles that will help you. Fast access to the information.

We also used the Codex site statistics to help us determined the most visited pages on the Codex. These we added links directly to the page to help the user again get immediate access to the information they need.

The plan was to create a look that was:

  • Easy to read
  • Easy to scan
  • Put the most important information at the top

Through some very creative use of HTML, CSS, and Mediwiki tags, we created a uniform look that complements the WordPress site and puts the focus on the information and access to it.

The Featured Article

Now that the WordPress Codex was about to have a new look, it was also time to take advantage of the amazing amount of documentation available on the Codex. At the bottom of the page we created a “Featured Article” section that highlights a different article or collection of related articles every week. We used the features of Mediawiki to make this change automatic.

It also gives us a chance to show off some of the great articles, writing, and information the Codex has to offer. A lot of effort goes into each article, from conception to editing, and they are always being monitored to make sure the information is as accurate as possible. Thank you to everyone who contributes to the WordPress Codex. This featured article section is just a small way of saying “thanks” to the many who have given so much time to the Codex.

To help you understand the why of things, again, we looked at our user’s needs. While most sites want to have information about their site and purpose, as well as events and activities, at the top, our users want information and help and they want it now. As fun as the featured article section is, it is information that is helpful and entertaining but not critical to the use of the Codex. After a lot of debate and design options, we choose to put it at the bottom, where it stands out and neatly closes the list.

Understanding how a user moves through a site and looks for information plays a very critical role in a site’s layout. We will continue to examine the pages that are most visited by users and evaluate their inclusion in the front page or placement in the subsection table of contents, and maybe we will change our minds and move this new toy, featured articles, up higher, but the goal is to get the information the user needs to him or her as soon as possible. We hope the new look meets that need.

Thanks to the WordPress Documentation Volunteers

We’ve been working on this new design, at least to this stage, for well over seven months. The changes have been small. The documentation team on the WordPress Documentation and Codex Mailing List helped tremendously, as did many of the volunteers who hang out on the very popular IRC Channel for #Wordpress (Direct Link) helping WordPress users get answers to their questions live.

The look of the Codex will continue to change and evolve, but we are really happy with this new look and we hope you will be, too. And if the new look inspires you to get involved, the WordPress Codex needs you. We need fixers, editors, writers, experts, and just folks to help us make the decisions that need to be made about the documentation users like you need to make WordPress work for you.


  • Craig Hartel
    Posted June 9, 2005 at 0:46 | Permalink

    You and the rest of the docs team have done a fantastic job. I hope that you all start getting the recognition that you deserve so much.

  • Posted June 9, 2005 at 1:25 | Permalink

    Well done, Lorelle! Very well done! Bravo!

  • Posted June 9, 2005 at 4:39 | Permalink

    Great work, Lorelle!

  • Posted June 9, 2005 at 5:38 | Permalink

    Nice work! Very intuitive interface.

  • Posted June 9, 2005 at 7:00 | Permalink

    Excellent article explaining the New Look. Great Job! The payoff for your hard work on Codex should be knowing how much easier it will be for users to get the information they need about WordPress. Just wondering where you’re going to put those 500 new articles you want for Codex :)

  • Posted June 9, 2005 at 8:04 | Permalink

    The great thing about the Codex is that it isn’t the work of just one person. The number of people who give so much of their time to help users…wow, it’s amazing.

    I would love to create a list of everyone who gives so much to WordPress, and thank everyone individually for making my small contributions possible, but I’ll resort to the old cliche: You know who you are, and remember you are not forgotten or ignored: Thank YOU.

  • Posted June 9, 2005 at 16:44 | Permalink

    It looks great, but the Featured Article really needs to be more featured, perhaps at the top or half way down? You have some great content in that wiki, hat tip to you all.

  • Posted June 11, 2005 at 16:49 | Permalink

    Great write-up! And you do an amazing job with the Codex. You sure earned that link that Matt promised.

4 Trackbacks

  • By All Narfed Up on June 9, 2005 at 1:25

    New Codex look

    Awesome job to Lorelle and the rest of the documentation team! If I refer anyone to WordPress, I’ll feel that much more comfortable pointing them to the WordPress Codex. I didn’t notice the change until PhotoMatt pointed it out, so thanks …

  • […] nice improvement. If you would like to know more, Lorelle has been kind enough to publish a comprehensive article on the thoughts that were behind this change. Posted by […]

  • By The Indiana Jones School of Management on June 9, 2005 at 10:28

    Codex: New Front Page

    Lorelle VanFossen explains the rationale behind the new look for the front page of the WordPress Codex. It’s pretty spiff!
    [HT to Matt.]

  • […] « Links with Attitude – Codex New Look – Taking Your Camera on the Road » WordPress Codex Has a New Look, The WordPress Codex has a new look. Not a complete change, but a good start… […]

Post a Comment

Your email is kept private. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.