Writing Tips

The  is written in second person familiar in English. This removes the “I” from the instructions and tutorials and puts “you” in the driver’s seat.

Here’s two paragraphs to compare the difference:

I needed to display my categories in the sidebar of my blog. To do this I went to the Widgets under Appearance and looked for the categories widget. I then dragged it to the spot I wanted it on the sidebar panel form to the right of the page. This did the trick!

Too personal, too much “I,” and not clear and easy to read instructions. This is how we would write the following on the WordPress Codex.

To display post categories on your WordPress blog:

  1. Go to the WordPress Administration Panels Menu > Appearance > Widgets.
  2. From the list of available WordPress Widgets, choose Categories.
  3. Click and drag Categories to the sidebar form on the right side of the panel to the appropriate place.
  4. To adjust the placement and sequence in which it appears on the sidebar:
    • Click and drag it up or down the sidebar form.
    • To edit the Category Options, click the small down arrow on the right of the Widget.
    • When the options are set, click Save.
  5. To preview the changes in your WordPress blog sidebar to check that the arrangement suits your needs.

Easier to read, gives you the information you need to know, removes all the editorial commentary that might make for fun blog reading but not good technical writing. People don’t come to the Codex for giggles. They arrive often desperate for help and just want the help and nothing more.

We have two similar writing voices and styles in the WordPress Codex. In most of the documentation, the goal is to keep the instructions clear and simple in a step-by-step format, not paragraph format. There are no “I” statements, only “you” as in “you do this” and “you move that.” Instead of explaining everything, terms and references are linked and the process continues forward.

The only section that is different are WordPress Lessons. These are meant for beginners, beginners to WordPress and possibly to the web and web publishing in general. These are written with the intention of making the reader feel like their helper is sitting right next to them at their computer, pointing out everything in the simplest of terms, making no assumptions about what they know already, just holding their hand through the process, one step at a time.

While it is often easy to include a link to an external resource to explain something better, link to internal documentation first, and add external resource links at the bottom of the article under “More Resources.” The purpose of the WordPress Codex is to become the source, so write accordingly.

Write timelessly. Yes, WordPress changes and evolves from version to version, but write as if this article will still have value five, ten, twenty-five years from now.

The Codex Docs team wrote up a Codex Voice, Style, and Audience and other documents to help you understand more about how to write for the WordPress Codex:

New articles are to be started on your Codex username space. Add the DRAFT template code to the top of the article while you are working on it so others will not edit it before you are ready. When ready for editing, let the Documentation Team know through the mailing list or on this site, and when ready, a senior team member will move the article into the main Codex.

More WordPress Codex Writing Tips

The WordPress Codex writing style is different from what you have done before. Here are some more tips to help you understand some of the details that makes that difference.

  • WordPress Themes and WordPress Plugins are capitalized even when using Themes and Plugins in a sentence without the WordPress.
  • Each article opens with an introductory paragraph or two simply explaining the purpose of the article. It does not need a heading. It should contain the keywords used to search for such a page.
  • It is not the admin area, backend, or dashboard. It is the Administration Panels or Administration Screens. You can call them panels or Panels or screens or Screens, or Panel Sections or any combination thereof, but they aren’t the other words. The Dashboard is a panel on the WordPress Administration Panels. When first referencing them, use the [[Administration Screens]] link.
  • Lists begin with capital letters not lower case. They may or may not include a period. If they are complete sentences, yes. If just words or phrases, not.
  • Code within a sentence is set with the deprecated <tt> HTML tag not <code>, which is used on individual lines for code blocks. We welcome a design change but until then, this is the practice.
  • Link to EVERY new concept or namesake to its Codex page when using it for the first time. If there isn’t an article on the subject, link to the reference in the Codex Glossary. If the word isn’t there and should be, add it. Don’t clutter it up with links, but make them make sense. Example, Twenty-Eleven WordPress Theme should link to the WordPress Theme Directory page for the Theme.
  • Use WordPress too much. Many people feel weird writing WordPress Plugins and WordPress Themes and referring to WordPress sites over and over again. It isn’t natural or expected in general articles but it is in the Codex. We call it by name, even if we say WordPress 5,000 times in the article. Be judicious, appropriate, and not excessive.
  • It’s WordPress site now, not WordPress blog.
  • There was a long debate over log-in, login, log in, and logged in. In general, login, log in, or logged in are acceptable. We tend to avoid the hyphenated version.
  • Be willing to use UK English if desired. We’re not strict on the Codex being Americanized.
  • Avoid using typical HTML in the Codex. Try to use the MediaWiki code first, HTML last. It helps with standardizing things when the design changes.
  • Use category templates at the bottom of the post to help the team know where to add it in the table of contents, etc.

Our goal is to provide clear, easy-to-read, easy-to-understand, helpful documentation and articles to serve the vast and diverse WordPress Community. Your words may help thousands learn how to use WordPress better, and each word is much appreciated.