====== Formatting guidelines ====== ===== General documentation structure. ===== Include following information in your piece of work. - Title. - Overview. - Requirements. - Version. - Actions. - 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 [[plugin-tuts:facebook-connect|Facebook Connect]] plugin correctly”, where “Facebook Connect” leads to docs.oxwall.org/plugin-tuts:facebook-connect. * Use examples to support your general description. // Proof read your documentation and use standard formatting.// ===== Standard formatting. =====

Formatting

Use formatting for:

Example:
''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''.

Result:
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.

Result:
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.|

Result:
* 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.

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

Result:
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.

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

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

Result:
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! - Captures only related to your topic area. - Is consistent to the text it is connected with. - Is 400px (correlation 4:3) size. - Is placed AFTER the text it belongs to. - Selections and arrows within the screen shot are: * color: red (#ff0000) * scale: 0.5px. Example: {{:contribute:samplescreenshot.png?400|}}