User Tools

Site Tools


Formatting guidelines

General documentation structure.

Include following information in your piece of work.

  1. Title.
  2. Overview.
  3. Requirements.
  4. Version.
  5. Actions.
  6. Results.

General writing style tips.

Be simple.

  • Use simple sentences. Each sentence should carry a well defined idea. One idea- one sentence. Avoid fitting all ideas into one long sentence separated by commas.
  • Avoid using passive voice and impersonal sentences.

Be consistent.

  • Provide step by step instructions on what should be done, where and how. Use “Action 1 → Action 2” formatting (see Standard Formating for more information) to define which actions come first.
  • Make sure that screen shots don't contradict to the text referring to them.

Be detailed.

  • Documentation readers are not experts. What seems obvious to you might require detailed explanation to others. Describe each step with as much details as possible.
  • Use links to user manual or other documentation if you are mentioning a general feature that has already been described. For example: “Before adding the code above make sure that you have set Facebook Connect plugin correctly”, where “Facebook Connect” leads to
  • Use examples to support your general description.

Proof read your documentation and use standard formatting.

Standard formatting.


Use formatting for:


''path/folder_name/filename'' File, folder and path names Input:
To edit amount of allowed attached files when sending private message go to ''ow_plugins/mailbox/classes/add_message_form.php''.

To edit amount of allowed attached files when sending private message go to ow_plugins/mailbox/classes/add_message_form.php.
**Button** Buttons, pages sections and feature names Input:
click **Save** and check your homepage once more.

click Save and check your homepage once more
Page 1 > Page Navigation between pages Go to Admin Panel > Settings > Languages
|**Note**: text | Notes to the text above the note. Input:
Hover the mouse over questions' name to see actions menu: delete and edit.
|**Note**: Username, password, email, real name, gender and birthday are system fields and can not be deleted.|

* log in to your control panel1* insert the code2 * refresh the page3 Bulleted list defining or describing available choices, options/actions Input:
*Delete-deletes user (profile and all of his files) from your site.
*Suspend-deactivates user.
*Re-activate-activates suspended users.

- item1 - item2 - item3 Numbered list defining or describing sequence of actions Input:
- log in to your control panel
- insert the code
- refresh the page

1.log in to your control panel
2.insert the code
3.refresh the page
<code> html/php/sql/css> a piece of </code > Highlight any piece of code. For example use <code php>Code here<</code> to highlight php code Input:
insert <code php> $multiUpload = new MultiFileField('attachments', 5);</code> and save changes.

insert $multiUpload = new MultiFileField('attachments', 5) and save changes.
http://[your_site_URL] Site links Input:
Documentation can be found at http://[]

Action 1 -> Action 2 Consistency between certain actions. Input:
Clear cache->Refresh page->Upload photo

Clear cache → Refresh page → Upload photo

Screen shots.

Screen shot is a very powerful way to explain your idea. If you screen shot matches following criteria, then you are good to go!

  1. Captures only related to your topic area.
  2. Is consistent to the text it is connected with.
  3. Is 400px (correlation 4:3) size.
  4. Is placed AFTER the text it belongs to.
  5. Selections and arrows within the screen shot are:
    • color: red (#ff0000)
    • scale: 0.5px.


contribute/documentation_standards.txt · Last modified: 2013/07/02 10:38 (external edit)