Differences

This shows you the differences between two versions of the page.

--- contribute:documentation_standards [2012/11/02 11:21]
Alia Approved
+++ contribute:documentation_standards [2013/07/02 10:38] (current)
@@ Line 1: / Line 1: @@
+====== 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. =====
+<html>
+<table>
+    <tr align="center">
+      <th><h3 style="text-align:center"> Formatting</h3></th>
+      <th><h3 style="text-align:center">Use formatting for:</h3> </th>
+      <th><h3 style="text-align:center">Example:</h3> </th>
+   </tr>
+   <tr>
+      <td>''path/folder_name/filename'' </td>
+      <td>File, folder and path names </td>
+      <td>
+           Input:
+            <br>To edit amount of allowed attached files when sending private message go to
+           ''ow_plugins/mailbox/classes/add_message_form.php''. <br><br>
+            Result:<br>To edit amount of allowed attached files when sending private message go to
+           <code>ow_plugins/mailbox/classes/add_message_form.php</code>.
+        </td>
+   </tr>
+   <tr>
+      <td>**Button** </td>
+      <td>Buttons, pages sections and feature names</td>
+      <td>
+           Input: <br>click **Save** and check your homepage once more. <br><br>
+           Result:<br> click <strong>Save</strong> and check your homepage once more  </td>
+   </tr>
+   <tr>
+      <td>Page 1 > Page </td>
+      <td>Navigation between pages </td>
+      <td>Go to Admin Panel > Settings > Languages </td>
+   </tr>
+   <tr>
+      <td>|**Note**: text | </td>
+      <td>Notes to the text above the note.</td>
+      <td>
+           Input:
+           <br> Hover the mouse over questions' name to see actions menu: delete and edit. <br>
+           |**Note**: Username, password, email, real name, gender and birthday are system fields and
+           can not be deleted.|<br><br>
+           Result:
+           <br> <img src="/_media/contribute:2screen.png?w=400">  </td>
+   </tr>
+   <tr>
+      <td> * log in to your control panel1* insert the code2 * refresh the page3 </td>
+      <td>Bulleted list defining or describing available choices, options/actions </td>
+      <td>
+           Input: <br>*Delete-deletes user (profile and all of his files) from your site.
+                  <br>*Suspend-deactivates user.
+                  <br> *Re-activate-activates suspended users.</br><br>
+           Result:
+                  <br><img src="/_media/contribute:3screen.png?w=350">
+   </tr>
+   <tr>
+       <td> - item1 - item2 - item3</td>
+       <td>Numbered list defining or describing sequence of actions</td>
+       <td>
+           Input: <br> - log in to your control panel
+                  <br>- insert the code
+                  <br> - refresh the page <br><br>
+           Result:<br>1.log in to your control panel
+                  <br> 2.insert the code
+                  <br> 3.refresh the page
+       </td>
+   </tr>
+   <tr>
+       <td>  &lt;code&gt; html/php/sql/css> a piece of &lt;/code &gt;  </td>
+       <td>Highlight any piece of code. For example use &lt;code php&gt;Code here&lt;&lt/code&gt; to highlight
+           php code
+       </td>
+       <td>
+           Input:
+           <br>insert &lt;code php&gt; $multiUpload = new MultiFileField('attachments', 5);&lt;/code&gt;
+           and save changes.<br><br>
+           Result:
+           <br>insert <code php> $multiUpload = new MultiFileField('attachments', 5)</code> and save
+           changes.
+       </td>
+   </tr>
+   <tr>
+       <td><nowiki>http://[your_site_URL]</nowiki> </td>
+       <td>Site links </td>
+       <td>Input: <br>Documentation can be found at http://[http://docs.oxwall.org/] <br><br>
+           Result:<br><img src="/_media/contribute:5screen.png?w=400"></td>
+   </tr>
+   <tr>
+       <td> Action 1 -> Action 2 </td>
+       <td>Consistency between certain actions. </td>
+       <td>Input:<br>Clear cache->Refresh page->Upload photo <br><br>
+           Result:<br> Clear cache → Refresh page → Upload photo </td>
+   </tr>
+</table>
+</html>
+===== 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|}}

Oxwall Software Documentation

User Tools

Site Tools

Differences

Page Tools