User Tools
contribute:documentation_standards
Table of Contents
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 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 |
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/documentation_standards.txt · Last modified: 2013/07/02 10:38 (external edit)
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 3.0 Unported
