====== 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.
|
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 |