Wiki Style Guide

From Habari Project

Jump to: navigation, search

Wiki Guides and Conventions

Please feel free to make changes which improve the Habari wiki at any time.

If you're keen to get more involved, consider joining the Wiki Working Group, and keep an eye out for the next WikiWeek.


This page describes how pages should be written and formatted in the Habari wiki.

Contents

Language

Wiki pages should use American English.

Tone of Voice

In keeping with Habari's emphasis on the community, articles in the wiki should be written as if a person speaking for the community were speaking directly to the reader. First person plural form should be used for when referring to the Community. "Habari follows the meritocracy model. We believe that this is the best way to develop our community. We hope that you will find this to be true." The tone should be informal but authoritative.

Users and Developers

The terms "Users" and "Developers" should be used only when referencing people actively acting in those capacities. They should never be used to refer to "classes" of people in the Habari community. Attempts should be made to minimize perceived differences between the two groups.

Heading Text

Text used for headings should be meaningful. On a tutorial page, it's fine to have a "Getting Started" section, but in general try to use headings that describe the contents of the section and avoid headings like "Let's Go".

Formatting

The word "Habari" should be capitalized and in plain text, as it appears in this page. Additionally, when referring specifically to the Habari Community, the word "Community" should also be capitalized.

Headings

Page and heading titles should capitalize the first character of words, except words such as 'the' and 'of'. Consecutive headings should be avoided. Instead, sections should have introductory text before subsections.

Code

All code used in wiki pages should adhere to the Habari coding standards, except that indentation should use two spaces rather than tabs to fit as much code on a line as possible. When code examples appear inline, they should be enclosed in tt tags. For example, <tt>echo "Spread the News!"</tt> will appear as echo "Spread the News!". When using a block of code, the code should be in code tags, with the lang attribute set to the appropriate value (most likely php or javascript).

For example, the following text:

<code lang="php">
<?php echo $post->content_out; ?>
</code>

will be displayed like this:

<?php echo $post->content_out; ?>

Only enough code but also enough context to illustrate the point being made should be included in code examples. When displaying multiple functions as within a class, use ellipses (...) to indicate that other functions or lines of code may exist.

Use inline comments to indicate that code might be omitted that serves a purpose that is relevant for the demonstration, but not germane to the topic. For example, if illustrating how a plugin filter is used to perform a search of records, provide the function definition with the appropriate parameters and return value, but include a comment that indicates how the input values are transformed into the return value. It is not strictly necessary to include the actual code for the search, since the topic being documented is how to implement the filter function itself, and the search code itself may be confused with the illustration required for the documentation.

Where possible, code examples should be taken from real code, either in Habari itself or from themes or plugins.

Links

Link text should not include the namespace of the target page. For example, the page about retrieving posts that is in the Dev namespace should be linked as Retrieving Posts. Text around the link should make the intended audience clear.

Organization of the Wiki

The Wiki Structure page describes how the wiki is organized, including what templates and categories should be used on pages. Please read it before creating any pages.

Personal tools
This is a cached copy of the requested page, and may not be up to date.

Sorry! This site is experiencing technical difficulties.
Try waiting a few minutes and reloading.

(Cannot contact the database server: Access denied for user 'habari'@'localhost' to database 'habari_wiki' (localhost))


You can try searching via Google in the meantime.
Note that their indexes of our content may be out of date.