Skip to content
This repository has been archived by the owner on Aug 23, 2019. It is now read-only.

Achievo wiki style guide

Jump to bottom
dalers edited this page Sep 7, 2012 · 3 revisions

Introduction

This wiki intends to provide well-organized consistent information for Achievo end users, administrators and module developers. This style guide outlines the administration and structure of the Achievo Wiki, and gives guidelines for creating and editing articles.

Who Can Use This Wiki?

Articles in this Wiki can be viewed by anyone. A member of the Achievo community with a valid GitHub account can create and edit articles.

Formatting, and Transparency over Brevity

The target audience for wiki articles can be assumed to be technically capable of installing and configuring a web and MySQL server with a PHP-based web application. Visibility and clarity of information shall take precedence over brevity. For example, URLs and inner links should not be displayed using titles and replacement text only to make the text shorter.

Article formats and syntax should either use GitHub markdown or MediaWiki syntax. For more information on GitHub markdown, refer to:

Terminology

Commonly used Achievo-specific terms and syntax are defined below for common understanding. Please add any missing terms.

  • term - definition

Headings

Headings should be used in their order of significance (i.e., Level 2, Level 3, ...), and heading levels should not be skipped (i.e. a Level 4 heading should not be used at the first heading in an article, or after a Level 2 heading).

Heading Level 1 should not be used in MediaWiki syntax (by MediaWiki convention, it is reserved for the MediaWiki system to use for article titles).

Code Examples

Start your code block with three back-ticks and "php" on its own line, and end the code block with three back-ticks, also on its own line.

function atkGroupByFilter($name, $groupbystmt, $flags=0)
{	
  $this->m_groupbystmt = $groupbystmt;
  $this->atkFilter($name, $flags);
}

When pasting in example code, be careful NOT to include unintentional HTML formatting tags (e.g. providing syntax color coding, keyword italicization, etc.) because it prevents easy copying of your code. The code should also preferably use spaces (instead of tabs) for indentation. If necessary, paste your example code into a pure text editor first to remove and correct formatting, then copy and paste from the text editor into the article.

Language

  • English shall be the standard language, with spelling according to the Standard American spelling, except for proper names and places. Set your spellchecker to US English and use it.
  • Non-English words should only be used when an English equivalent does not exist.
  • Acronyms should generally be capitalized, and an acronym should be defined the first time it is used in an article (e.g., "In a Windows environment, a WAMP (Windows/Apache/MySQL/PHP) installer is a convenient way to setup the web application stack for Achievo.").

Dates

  • Dates shall be given in ISO standard format (i.e., yyyy/mm/dd) or written out (e.g., “March 2, 2000”). “03/02/2000” can mean either March 2, 2000 or 3 February 2000, depending on the background of the author and reader.

Numbers

  • Punctuation within numbers should follow the American standard, with a period used as a decimal separator and digits in groups of 3 separated by a comma (e.g., 10,000.00).
  • Numbers should be written in English for legibility when their magnitude is not technically significant. E.g. “There are three buttons on the screen” instead of "There are 3 buttons on the screen", and “a 10 MB file” instead of “a ten MB file”.

Screenshots and Images

  • Images shall be in PNG or JPEG (.JPG filename) format (preferably PNG, with filesize less than 20KB).
  • The ''achievo modern'' theme should be used for all screenshots.

Citing and Attribution

References for information shall be cited, and attribution given to their authors. A citing shall use the Chicago Author-date style (The Chicago Manual of Style Online. Chicago-Style Citation Quick Guide. http://www.chicagomanualofstyle.org/tools_citationguide.html (accessed 2010-02-01)).

For example:

  • Book, One Author: Doniger, Wendy. 1999. ''Splitting the Difference''. Chicago: University of Chicago Press.
  • Book, Published Electronically: Kurland, Philip B., and Ralph Lerner, eds. 1987. ''The Founders’ Constitution''. Chicago: University of Chicago Press. http://press-pubs.uchicago.edu/founders/ (accessed 2010-02-01).
  • Website: Evanston Public Library Board of Trustees. Evanston Public Library strategic plan, 2000–2010: A decade of outreach. Evanston Public Library. http://www.epl.org/library/strategic-plan-00.html (accessed 2010-02-01).
Clone this wiki locally