1,774
edits
Changes
Created page with "== Overview == This style guide provides the guidelines to which additions and changes to this Veloopti help should adhere to. This is to ensure that there is consistency with..."
== Overview ==
This style guide provides the guidelines to which additions and changes to this Veloopti help should adhere to. This is to ensure that there is consistency within the many articles and enforces our best practice in usage, language and visual composition.
Write to the user
You should, or You will have to are acceptable. Don't talk about the user in the third person
Tell the user what to do they are not left wondering what they should do
== Language ==
Australian English is used throughout the site.
=== Perspective ===
You should write in the second person. Writing in the second person requires use of the pronouns you, your, and yours. This point of view is commonly used to address the audience in technical writing and as such you should use it here also.
Here are examples of writing in second person:
# To make lemonade, you add the juice of lemons to water and sugar;
# To calculate the area of a room, multiply the width by the length;
# To add oil to your car engine, unscrew the cap, place a funnel inside, and slowly add the oil.
=== Capitalisation ===
Capitalisation should only be used when it increases the meaning that is held in the words. For the most part don't capitalise unless it helps to clear up any ambiguity.
=== Bold ===
You should use bold sparingly. It should be used to enable the reader to skim the article to quickly find the thing that they are looking for.
=== Italics ===
Use italics for the common things that it is used for: ''i.e.'' the usual things; ''and'' the last item with an in-line lists.
== Items ==
=== Buttons ===
Buttons should have the picture copied from the Veloopti website and referenced, ''e.g.'' Click the [[file:Update_profile_button.png|80px]] button to update your profile.
=== Menu items ===
Menu items are selected and not clicked so tell people to select the '''Dashboard''' menu item, not click it. The item that is selected should be bolded, ''e.g.'' Select the '''Dashboards''' menu item to view the available dashboards.
Menu sub-items are menu items that are lower than the main menu item. They should be referred to as: Select the '''Dashboards -> favourites''' menu item to select your favourite dashboard.
=== Keyboard ===
When telling the user to use the keyboard, use the {{Key press}} template ''e.g.'' <code>{{Key press|Enter}}</code> for {{Key press|Enter}}.
=== Code ===
Code should be written surrounded in <code> and </code>; thus in the form: <code><code>question = /(bb|[^b]{2})/</code></code>.
This results in the following output: <code>question = /(bb|[^b]{2})/</code>
=== Warning boxes ===
The [[file:Warning.png|15px]] icon should be used when you want to alert the reader to something. Also make sure you put five spaces and then '''Note:''' in all bold (one day I'll get that turned into a template). <Code>:[[file:Warning.png|20px]] &#160; &#160; &#160; &#160; &#160; &#160; '''Note:'''</code>
: [[file:Warning.png|20px]]           '''Note:''' Do remember to indent it.
== Categories ==
Categories are used to make things easier to find. There are two different type of categories in the Veloopti Wiki:Category tree; ''and'' Category types.
=== Category tree ===
The category tree is used to contain the articles into a tree structure. The tree structure is designed to make things easy to find. The current category structure is:
<categorytree mode=pages>Contents</categorytree>
=== Category types ===
Any articles in the Wiki can contain the following categories. These categories spread across multiple category trees and are used to pull things together.
# [[:Category:Actions|Actions]]
# [[:Category:Agents|Agents]]
# [[:Category:Billing|Billing]]
# [[:Category:Dashboards|Dashboards]]
# [[:Category:Events|Events]]
# [[:Category:Logs|Logs]]
# [[:Category:Metrics|Metrics]]
# [[:Category:Nodes|Nodes]]
# [[:Category:Notifications|Notifications]]
# [[:Category:Organisation|Organisation]]
# [[:Category:Outages|Outages]]
# [[:Category:Policies|Policies]]
# [[:Category:Tasks|Tasks]]
# [[:Category:Users|Users]]
[[Category:Contents]]
This style guide provides the guidelines to which additions and changes to this Veloopti help should adhere to. This is to ensure that there is consistency within the many articles and enforces our best practice in usage, language and visual composition.
Write to the user
You should, or You will have to are acceptable. Don't talk about the user in the third person
Tell the user what to do they are not left wondering what they should do
== Language ==
Australian English is used throughout the site.
=== Perspective ===
You should write in the second person. Writing in the second person requires use of the pronouns you, your, and yours. This point of view is commonly used to address the audience in technical writing and as such you should use it here also.
Here are examples of writing in second person:
# To make lemonade, you add the juice of lemons to water and sugar;
# To calculate the area of a room, multiply the width by the length;
# To add oil to your car engine, unscrew the cap, place a funnel inside, and slowly add the oil.
=== Capitalisation ===
Capitalisation should only be used when it increases the meaning that is held in the words. For the most part don't capitalise unless it helps to clear up any ambiguity.
=== Bold ===
You should use bold sparingly. It should be used to enable the reader to skim the article to quickly find the thing that they are looking for.
=== Italics ===
Use italics for the common things that it is used for: ''i.e.'' the usual things; ''and'' the last item with an in-line lists.
== Items ==
=== Buttons ===
Buttons should have the picture copied from the Veloopti website and referenced, ''e.g.'' Click the [[file:Update_profile_button.png|80px]] button to update your profile.
=== Menu items ===
Menu items are selected and not clicked so tell people to select the '''Dashboard''' menu item, not click it. The item that is selected should be bolded, ''e.g.'' Select the '''Dashboards''' menu item to view the available dashboards.
Menu sub-items are menu items that are lower than the main menu item. They should be referred to as: Select the '''Dashboards -> favourites''' menu item to select your favourite dashboard.
=== Keyboard ===
When telling the user to use the keyboard, use the {{Key press}} template ''e.g.'' <code>{{Key press|Enter}}</code> for {{Key press|Enter}}.
=== Code ===
Code should be written surrounded in <code> and </code>; thus in the form: <code><code>question = /(bb|[^b]{2})/</code></code>.
This results in the following output: <code>question = /(bb|[^b]{2})/</code>
=== Warning boxes ===
The [[file:Warning.png|15px]] icon should be used when you want to alert the reader to something. Also make sure you put five spaces and then '''Note:''' in all bold (one day I'll get that turned into a template). <Code>:[[file:Warning.png|20px]] &#160; &#160; &#160; &#160; &#160; &#160; '''Note:'''</code>
: [[file:Warning.png|20px]]           '''Note:''' Do remember to indent it.
== Categories ==
Categories are used to make things easier to find. There are two different type of categories in the Veloopti Wiki:Category tree; ''and'' Category types.
=== Category tree ===
The category tree is used to contain the articles into a tree structure. The tree structure is designed to make things easy to find. The current category structure is:
<categorytree mode=pages>Contents</categorytree>
=== Category types ===
Any articles in the Wiki can contain the following categories. These categories spread across multiple category trees and are used to pull things together.
# [[:Category:Actions|Actions]]
# [[:Category:Agents|Agents]]
# [[:Category:Billing|Billing]]
# [[:Category:Dashboards|Dashboards]]
# [[:Category:Events|Events]]
# [[:Category:Logs|Logs]]
# [[:Category:Metrics|Metrics]]
# [[:Category:Nodes|Nodes]]
# [[:Category:Notifications|Notifications]]
# [[:Category:Organisation|Organisation]]
# [[:Category:Outages|Outages]]
# [[:Category:Policies|Policies]]
# [[:Category:Tasks|Tasks]]
# [[:Category:Users|Users]]
[[Category:Contents]]