Documentation Issue Tracker on GitHub: Submit any Documentation Team-related issues on GitHubGitHubGitHub is a website that offers online implementation of git repositories that can easily be shared, copied and modified by other developers. Public repositories are free to host, private repositories require a paid subscription. GitHub introduced the concept of the ‘pull request’ where code changes done in branches by contributors can be reviewed and discussed before being merged be the repository owner. https://github.com/
Join our discussions of documentation issues here on the blog and on Slack.
The WordPress Codex 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 sidebarSidebarA sidebar in WordPress is referred to a widget-ready area used by WordPress themes to display information that is not a part of the main content. It is not always a vertical column on the side. It can be a horizontal rectangle below or above the content area, footer, header, or any where in the theme. of my blog. To do this I went to the Widgets under Appearance and looked for the categories widgetWidgetA WordPress Widget is a small block that performs a specific function. You can add these widgets in sidebars also known as widget-ready areas on your web page. WordPress widgets were originally created to provide a simple and easy-to-use way of giving design and structure control of the WordPress theme to the user.. 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 CodexWordPress CodexLiving online manual to WordPress.org https://codex.wordpress.org/.
To display post categories on your WordPress blog:
Go to the WordPress Administration Panels Menu > Appearance > Widgets.
From the list of available WordPress Widgets, choose Categories.
Click and drag Categories to the sidebar form on the right side of the panel to the appropriate place.
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 CategoryCategoryThe 'category' taxonomy lets you group posts / content together that share a common bond. Categories are pre-defined and broad ranging. Options, click the small down arrow on the right of the Widget.
When the options are set, click Save.
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.
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> HTMLHTMLHTML is an acronym for Hyper Text Markup Language. It is a markup language that is used in the development of web pages and websites. 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.