Codex:Guidelines

Welcome! 

These are the few standards that the documentation team aspires to adhere to.

Meta Rules

1. Release early and often.
2. Edit mercilessly.
3. Have fun. :)

Standard Practices

Creating New Pages

1. All registered users may now directly create new pages. However, please read, understand, and follow all of the following guidelines in order to create the best page possible with the least amount of work having to be done. After you have created a page, ensure that you add {{review}} at the bottom of the page so that it will be flagged for quality assurance checks for page name, adherance to guidelines, and a copy edit process.
2. Use the Sandbox page for practice: The Sandbox is a great place to get your feet wet without worrying about goofing something up.
3. Search the Wiki before creating new pages: Make sure a page doesn't already exist by searching for it at the Codex. Use the All Articles page to make sure you are not duplicating work.
4. Do not create dead-end pages: If you have to create a new page, do so by adding a wiki link to the intended page from another page. Good choices are pages which seem to be logically related to the new page, like an organizer page, or a page that requires the new page to describe something in detail. This practice will make the job of organizing pages in a logical fashion much easier.
5. Do not use CamelCase for page titles: The Codex does not use CamelCase like some other wikis do. All page titles and therefore links should be of normal title case. For example, the page about Codex should have the title"About Codex", with the link formatted as: [[About Codex]] and not the CamelCase [[AboutCodex]].
6. Use Title Case for Page names: These should be full titles, so instead of "IntroToGallery" have "Introduction to Gallery". 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)
7. Namespace: Pages related to the Codex should be prefaced with Codex:; pages related to Gallery 1 should be prefaced by Gallery1:; pages related to Gallery 2 should be prefaced by Gallery2: (e.g. "Gallery1:Installation", "Gallery2:Developer Starter Kit").
8. Create and Use Sub Pages Sparingly: The Codex standard is to minimize the creation of sub pages.
9. Empty pages: Please do NOT create blank pages simply as placeholders. Once the pages are created, they are live, and any links to them will work. When a user clicks their way to an empty page, they have wasted their time. Please -- only create pages when you have some content to put into them. Create them initially as a sub-page. You need not have a complete page, but there should be something of value there for users. As described above, create a sub page in your USER: page if you want to start on the draft for a new page, or use the Sandbox for practicing.

Requesting New Documentation

See: Documentation Requests

Categories

The following categories has been defined, and all content should be categorized: Special:Categories

You place content into categories by using the [[Category:Gallery 1:Installation]] notation. All content on the codex should belong in one of the above mentioned categories, and the category markup should be placed on the bottom of the page.

If you are unsure which category your content belongs in, use the {{nocat}} template at the top of the page to help identify them to the docs team.

Ensuring Correctness

1. Proofread: Ensure your work has proper spelling and grammar. If you move a page over from the old documentation, then take the time to examine the page when you move it over and make any necessary changes.
2. Marking Incomplete pages: If you think a page is incomplete, mark the page as such by using the Stub template. You do this by inserting the following tag: {{expand}}. (NOTE: The tag is case-sensitive!)
3. Marking Duplicate pages: If you think that Page A is a copy of Page B, or even close, then please use {{merge}} to tag the pages as requiring merging.
4. Marking Pages to be deleted: If you find a page that should not, or need not be there, or is inappropriate, edit the page to have the {{afd}} tag. This will alert a maintainer to look into it for deletion.

Discussions

1. 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. If you notice at the top, every page has a DISCUSSION tab on it, which is the place to make your comments, suggestions, and such. Thank you!
2. Leaving Messages for Users: Leave a message for a use by editing the User:Talk page associated with the user. The user will receive a visual prompt the next time they visit the Codex and Login.
3. Separate Comments: Please create a horizontal rule between comments on the discussion page by using four dashes ---- between entries.
4. Always Sign Your Comments: To add your "signature" to a comment, add four ~s (tildes) at the end of your comment. This will list your User Name and a link to your User Page and add a time-stamp. This is very useful for discussion pages. An alternative method is to click on the signature icon at the top of the edit window...it's the second one from the right.

Conventions

1. 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 RFC2606. For an example Gallery URL, use the template "exampleurl" to produce an example (e.g. {{exampleurl|/setup}} produces http://www.example.com/gallery/setup)
2. Admin: The main admin user always has the login admin
3. Using People's Names in Examples: When a name is needed for an ordinary, non-admin user, or a person, use "Bob" as the first name.
4. Page Titles: Try not to use "Gallery" in the title of Codex pages (i.e. err to "Installing" rather than "Installing Gallery")

Patrolling

When some users make edits they are automatically marked as patrolled. It applies to all sysop users and any users we have added to a group called autopatrol. We have also increased the time we keep data in the Recent Changes list from the default 7 days up to 30 days.

Use this view Patroll View

If you monitor codex at all, please do mark changes you review as patrolled. Clicking the "diff" links (or the article link for new articles) from the Recent Changes view will give you the "mark as patrolled" link in the next page (in the diff header on the right side, or at the very bottom for new articles). If the change looks mostly ok but needs some edits, still mark the revision as patrolled, then make your edits.

Add a user to the autopatrol group at: Special:Userrights

Use of Images, Graphics, Flash, and Video

A picture is worth a thousand words and this is certainly true when creating documentation. Consider using screenshots to illustrate complicated subjects. Please consider the following when incorporating imagery.

• Optimize images for the Web
• Images should be no larger than 600px wide at 72 d.p.i.
• Scale images with an image editor rather than with HTML or CSS
• Do not scale images up from their original size
• Upload images to the codex rather than referencing them externally
• Ensure legibility of text in images

If pictures are worth a thousand words than animation is worth much more. We prefer the use of Flash-based demonstrations over movies becuase they are relatively smaller in file size. Windows users can generate Flash demonstrations with free screen capture animation tools like Wink.