Languages: English • Español • 한국어 • Português do Brasil • 中文(简体) • (Add your language)
This article seeks to outline recommended practices for editors and volunteers at WordPress Codex. Should you have a suggestion for improvement, please post a note on the WordPress Documentation mailing list.
New articles and pages are welcome. There is a process, though.
Please use predefined and conventional formatting by following the Codex Styles for articles established here: Editing Help.
The following are guidelines for contributing new work to the Codex:
Use the following "stubs", categories which designate the state an article is in:
Predefined formatting markup is here to help you produce good looking articles and maintain a consistent look throughout the WordPress Codex. Please see the Editing Help article to learn how to use the correct markup for headings, paragraphs, character formatting, links, multimedia, etc. In the Character Formatting section of that article, you will also find the recommended formatting for text with various emphasis or quality, such as terms and filenames.
Although WordPress Codex uses the wiki markup for general formatting, there are some specifics which you should adhere to when making your contribution, such as when you want to show some examples or code samples. See Codex Styles for more information and tips about these specifics.
Layout of WordPress Codex articles follows a simple convention. An article normally starts with a descriptive paragraph, though sometimes it may start with a section heading followed by an introductory paragraph. Following that, then the rest of the article is presented, and is divided into concise sections of information, examples, and images that help WordPress users understand the concept under discussion.
Try to stick with the topic of the article and make references to other WordPress Codex articles or sections within the same article where possible.
Resources are usually found at the end of the article in the section titled "Resources" and may include links to external sites. External links should be limited to the most reliable and consistent sources, preferably non-commercial sites, when possible.
You should also provide a section titled "Related" to allow visitors to effortlessly continue reading by visiting a related topic within a WordPress topic, or to help them find what they were initially looking for. The Related section is placed right after the Resources section at the end of the article, like in this article.
All headings must also be in Title Case. For example, use "Using the Links Manager" not "Using the links manager." These should be full titles i.e., not "IntroToBlogs" but "Introduction to Blogs."
They should also follow the Dr. Grammar rules regarding capitalization thus: "In titles, capitalize the first word, the last word, and all words in between except articles (a, an, and the), prepositions under five letters (in, of, to), and coordinating conjunctions (and, but). These rules apply to titles of long, short, and partial works as well as your own papers" (Anson, Schwegler, and Muth. The Longman Writer's Companion 240)
[[About Codex]] and not the CamelCase [[AboutCodex]].Use internal links to direct the visitors to a specific topic covered in more detail by another article within WordPress Codex to keep the original article concise. You may also use internal links to point out that a special term is being mentioned, linking the term with the particular Glossary section or related article, or when describing where to find a specific feature, like: Administration Panels > Plugins > Add New. However, do not create links on every occasion, create them only when referring to a term, feature or article for the first time, except for when describing a path as above, because... it's handy and looking good :-)
Internal links to other articles that are closely related to the topic of the referring article, such as those from the same category, are listed in the Related section at the bottom of Codex articles.
External links are to be used judiciously as they can be notoriously difficult to maintain and verify. Use your best judgment, but consider the following when choosing to include an external link on the WordPress Codex:
External links are listed in the Resources section at the bottom of Codex articles. If they are included within the content, application of the above qualifications becomes even more stringent.
With the official directories in place for WordPress Plugins and Themes, all links to Plugins and Themes must only be to those listed within the directories. Links to authors' sites is not permitted.
The WordPress Codex documentation team is often faced with questions and decisions to remove links on the Codex to questionable sites. The following should hopefully clarify the decisions and actions.
All links in violation of these terms shall be removed.
Each article within the WordPress Codex is categorized with specific categories, as listed on the Special:Categories listing. Please use one or more of the categories listed and do not add any new categories without approval from the WordPress Codex Documentation Team as a lot of work has gone into developing these categories.
To add a category to a page, at the bottom of the page use the following code, taking care to use the exact spelling and format from the Special:Categories list.
[[Category:Category name]]
An example would be:
[[Category:WordPress Lessons]]
Localization: For non-English language documents on the WordPress Codex, please use the two letter language code before the Category Name to group language specific documents:
[[Category:fr:Panneaux_Administration]]
You may also include the language-specific category for all documents in that language, such as:
[[Category:Turkish Codex]]
Link to a Category: To create a link to a category, use a colon before the word "Category" and add the link text for improved readability, such as:
[[:Category:WordPress_Lessons|WordPress Lessons]]
Which will appear in a sentence as:
Category Pages: Category pages are created automatically and customized by the WordPress Codex Documentation Team to include related and subcategories.
More Help: For more help on understanding how categories work in the WordPress Codex and MediaWiki, see Help:Editing and MediaWiki Help on Categories.
The WordPress Codex features parent categories and child categories (subcategories), which reflects the general table of contents. The content is currently grouped as follows:
Under Getting Started With WordPress are categories such as WordPress Lessons, WordPress Help, Getting Started, and Troubleshooting. Under "Working with WordPress" would be Conditional Tags, Feeds, Functions, Template Tags, Templates, and WordPress Optimization.
Some categorization makes sense. If an article is about WordPress Plugins, the Plugins definitely applies. However, what level of technical information is in the article? Who will benefit the most from reading it? If it is really basic, then it should be also categorized in the WordPress Lessons category. If it is advanced and technical, such as the coding and writing of Plugins, then it shouldn't be in the WordPress Lessons category. It should be in the Advanced Topics and/or WordPress Development, depending upon the sophistication of the information. Use your best judgment.
Categories in the WordPress Codex are added by the senior members of the WordPress Codex Documentation Team and reflect the table of contents of the Codex. In general, the criteria for adding categories to the Codex are:
Do not create sub-pages of a page, other than from your own User page, without discussing it first on the wp-docs mailing list. Exceptions to this are the pages under Function Reference (each of which describes a single function).
Using the "Talk" pages
Do you see something that is perhaps incorrect, or needs clarification? The best way to make mention of any issues is to use the Discussion function. Please refrain from adding your comments directly onto the article page. At the top of every page is a Discussion tab. This is the place to make your comments, suggestions, and such. Thank you!
The "voice" of the WordPress Codex is one of authority, but also a friendly conversational voice. The style of the Codex is to educate by providing simple and easy-to-use explanations when possible, and technical advice when necessary.
In general, articles are written to the reader, taking the reader through the process. The pronoun "I" is rarely used, focusing on "you click here" and "you open the template file". It is not about what you, the author, did, the story behind your decisions, or all the people who helped you succeed. It is about what the user needs to do in order to get their WordPress site up and functioning fast.
Bullets and lists are used to highlight the steps necessary to outline and streamline the process. Complicated tasks are broken down into small steps, guiding the novice or advanced user quickly to the solution.
The audience is extremely varied in ability and skill in HMTL, XHTML, CSS, and PHP. Articles found within the Advanced Topics and Developer Documentation are targeted for the experienced user. WordPress Lessons are designed for the novice, using language as if the author was the technical support volunteer sitting down next to the user at the computer, guiding them through the process. The rest of the Codex is targeted towards the beginner to intermediate level user and should contain simple language with links to definitions within the Glossary when necessary.
Whenever you edit a page you will see a checkbox with the label "This is a minor edit" above the save button. You should check this checkbox whenever you are making only a minor edit to a page. Examples of minor edits would be grammar and spelling corrections, small code formatting changes, etc. Minor edits are denoted by a lowercase "m"; for example on the recent changes page. If you are ever unsure whether your edit should be considered a minor edit or not, then leave the checkbox unchecked.