Wiki guidelines

phpBB Wiki Guidelines: A document outlining the information that should be considered when dealing with articles on the phpBB.com wiki.

Quality of articles
Important features when writing an article.


 * Structure


 * It is recommended that the very first line of a wiki article gives a brief description of the article. This allows users reading the article to immediately realise whether the article will be of use to them. A good example of this is in Cache where the first line says that "The cache system provides an API for caching frequently used data, it provides an interface for user code to cache data and an interface for the DBAL to cache query results."


 * Articles that are quite long should be split into sections. Each section should contain one subject matter, although a section can also be split into subsections also which is very useful if a particular subject is very detailed. Sections and sub-sections will be displayed in a table of contents automatically, so ensure section names are given informative titles. This includes giving a brief description of code examples in the section/sub-section title instead of just "Example 1", "Example 2", etc.


 * Flow of an article is important, so where appropriate similar information should be grouped rather than spread throughout an article.


 * Examples


 * If possible, and if it will help explain a concept, a code example should be included in the relevant programming language.


 * Quality


 * A wiki article should be written in such a way that a user with a reasonable background in programming - which is to be expected of users looking at the wiki - is able to follow what is being discussed. Often, this will mean giving a short explanation of a code block and elaborating on unfamilar concepts (or linking to another wiki article which will) instead of assuming a user already has that knowledge.

Naming articles
Articles should first be considered for a prefix (see 'Categorising articles'). Then an article name should be chosen. The name should be concise, while still giving an adequate indication of what the article is about.

In most circumstances the first letter of the title should be capitalised, and the first letter of all following words should only be capitalised if necessary (such as for proper nouns). For example, an article should be titled "Template_syntax" instead of "Template_Syntax".

For function names or special circumstances where the first letter would not be capitalised in common usage (such as user_add, phpBB3, etc) then the first letter should be left lower case after the prefix.

Categorising articles
There are several distinct types of wiki articles which should have their titles prefixed. This means that articles titles will look like Prefix.Article_name.


 * Tutorial


 * A tutorial is a broad overview of a particular subject. Generally, a tutorial is geared towards non-specific implementation of a concept but instead gives users the pre-requisite knowledge to use in their desired project.


 * For example: Permissions_Guide, Template_Syntax


 * Practical


 * These wiki articles are those that have a practical use for many users. A practical article could be seen as something that has specific "real life" applications.


 * For example: External_login, Displaying_posts_and_topics_on_external_pages.


 * Function
 * For use if a wiki article is describing a standard function of phpBB3. These wiki articles should also contain information regarding the function signature and parameters.


 * For example: User_add, Request_var


 * Classes


 * If a wiki article is detailing a method that is part of a phpBB3 class then it should be prefixed with:


 * Template for methods in the $template class
 * Dbal for methods in the $db class
 * User for methods in the $user class
 * Auth for methods in the $auth class
 * Umil for all things related to Umil


 * Note: For all tutorials or practical use articles regarding any of these classes they should be prefixed accordingly, and not with the Template/Dbal/User/Auth/etc prefix.


 * For example: Template.assign_vars, Template.assign_block_vars, User.setup


 * Table


 * All wiki articles about database tables should be prefixed with the word Table.


 * For example: Table.phpbb_bbcodes, Table.phpbb_profile_fields_data

Duplicate articles
In the case of two or more wiki articles covering the same subject matter, where possible the articles should be merged into the more indepth article. Duplicate information should be removed, with the more detailed/helpful information being retained.

The deleted article should thereafter redirect to the new merged article.