Oxwall Software Documentation

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== 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

Page Tools
