Codex Standards & Guidelines

If you are considering contributing to the codex this simple guide is here to help you with the formatting of pages and standards & conventions to follow to keep a set appearance to pages.

The Codex is curated by a team of volunteers they will check and verify articles for accuracy and adherence to Codex Standards, this is in order to maintain a consistent quality of article and standard throughout the codex. If you notice any articles of concern or think something is outdated or needs checking please contact one of the team members, if you are sure an article contains content that needs attention you may edit it and add a warning to the top of the article – please see the bottom of this page for markup to be copied and used in such circumstances.

Please note: All entries to the Codex are covered by the GNU General Public Licence. All entries may be edited or altered by other contributors.

Sections

• How to Create a New Codex Article
• How to Edit/Update an Article in the Codex
• Codex General Guidelines
• Codex Conventions
• Formatting Guide
• Adding article header messages

How to Create a New Codex Article

1. Log in using your WordPress username and password.
2. Click on the “Create New Page” link under the header or click on the “+New > Page” link on the WP Toolbar
3. Add the Title of your article
4. Add the article metas: Versions, Components, Types and Context. Meta boxes are located on the screen’s right sidebar
5. Add your article in the appropriate codex section in the Page Attributes meta box under the Context box.
   For reference, please go to the BuddyPress Codex Table of Contents which is updated regularly to guide you where to place your article
6. Add content of your article. Check that it follows the Codex General Guidelines, Codex Conventions, and Formatting guides posted below for your reference
7. After you’re done, click on the “Publish” button

How to Edit/Update an Article in the Codex

1. Log in using your WordPress username and password
2. Navigate to the page you want to edit/update
3. Click on the “Edit Page” link under the header of the page or click on the “Edit Page” link on the WP Toolbar
4. After you have made the edit/update, please double-check that the Versions, Components, Types and Context are correct and updated as well
5. Click on the “Update” button in the Publish meta box

General Guidelines

Broad guidelines on writing for the BuddyPress Codex

• When writing articles please use the second-person point of view to address the reader. e.g. “Now navigate to your” Rather than “Now navigate to our“
• When writing technical articles (functions, actions, etc.) please use the draft template you will find in the dashboard, copy and paste it’s body outline markup to your new post
• Please keep styling to a minimum, avoid inline styling of elements unless to provide something like a color highlight if thought necessary to lend further emphasis to a piece of text e.g styling a warning in red Ensure you have backed up your DB. Please use elements sparingly <b>, <i> are typographic conventions and used to embolden text and italicize text for foreign & scientific words/phrases; <strong>, <em> are to lend weight or importance to a word or phrase i.e ’em’ is not used simply to visually style text in italics
• Links: External resource links: Provided to the bottom of the article framework is a section for links to external resources, please use this section for any links to resources that help further however please ensure that these links are additional resources and that your article does not depend on them for all or any part of your article explanation, the reasoning here is external links are not guaranteed to always be available and if the article relies on them and they are down then the article is effectively useless for users. Links that are not related directly to the article content are to be avoided and if found will be removed
• Images: Do add images to articles where they help to illustrate your points or explanations, nothing helps illustrate things better than a timely graphic, screen shots of BuddyPress or WordPress screens help to show the reader layouts. As with links please avoid calling remote images, always upload to the media library, and embed. If uploading images please ensure you have the right to do so and are not infringing on any copyrights that may exist. Any images thought to be or that are under copyright will be removed from pages
• Creating pages: When creating pages , please ensure you select a suitable ‘Version’ tag, and optionally select from available ‘Components’ tags & ‘Types’. Please only select a parent category from the available parent sections, We request that authors DO NOT create new pages that act as parent pages for their article/s, this is to ensure the integrity of the codex structure, however it may be possible to expand the structure if thought beneficial, but please make a request for this to one of the Codex curation team members for consideration

Codex Conventions

• Website Example Names: Always use example.com, example.org or example.net wherever you need to state a domain as an example. This is per RFC 2606.
• Admin: The username admin describes the default administrator account of a WordPress installation in examples (admin should never be used on a live site due to negative security implications).
• Using people’s names in examples: When a name is needed for an ordinary, non-admin user, or a person, use Harriet as the first name, and Smith as the last name
• Administration Panels: The WordPress interface is called Administration Panels not admin panels or dashboard. Dashboard is a specific panel within Administration Panels. Individual panels are also called Administration Screens
• WordPress is spelled WordPress: WordPress is spelled with two capital letters: WordPress
• BuddyPress is spelled BuddyPress: BuddyPress is spelled with two capital letters: BuddyPress

With thanks to WP codex guidelines for borrowed bullet points: WP Codex:Guidelines

Formatting Guide

If writing a technical guide please use the template format provided in this draft document ( copy paste to new page ) Codex template – technical examples layout

1. Heading Tags:
Use h3 – h6. For example, on this page h3 is used for “Sections” above and for the title of this Section, “Style and Formatting“.

2. Code examples: Surround your code with the appropriate shortcodes
[php] your PHP code [/php]
[html] your HTML code [/html]
Also available are bash, shell, css, diff, patch, js, javascript, plain, text, sql and xml and are used in the same format as the previous examples.
N.B: When adding code examples please escape angle brackets < > with Numeric/Decimal entities rather than ‘Named ones, so use &# 060; and  &# 062;

3. Lists: Use unordered and ordered lists where appropriate.

4. File names: Surround file names with the code tags

<code>index.php</code>

5. The structure of a technical guide

Flagging articles – adding article header messages

Page may be tagged in the body with two ‘Notes’

1/ This page is a legacy document (at top of page)
if a page is deemed to be outdated or superseded by BP versions, or changes then it may be marked with this code block

and the page would be re-assigned under the parent section ‘legacy’

2/ This page is in need of updating

A page is considered incomplete or needs to be verified for detail.