HighFidelity:Style guide

From High Fidelity Documentation
Jump to: navigation, search

All documentation should be formatted in wiki markup and follow the guidelines below. For API reference documentation, please follow the API Template.

Title

Brevity and descriptiveness are key – what will encapsulate the contents of your page in just a few words? A good title will help it show up first when someone does a search on the wiki. Articles with titles matching searches show up in the list before articles that have content matching the search phrase.

If the first letter of your article title should be lowercase, you can put {{lowercase}} at the top of your page to make the wiki display title with the first letter lowercase. Example: addEntity().

Titles should not end with '.js' - this can cause formatting issues with MediaWiki.

Introduction

Include an introduction that lets the reader know the general level of the article, topics covered, and relevant prerequisites. Make sure that you include the relevant version of your High Fidelity build (and other relevant software and hardware) in your documentation.

Introductions go at the top of a wiki article and should not start with a header.

Tone

As not everybody is a native speaker of English, try to use simple, easy to understand language throughout your tutorial. As beginners might benefit from a level of hand-holding that may irritate more advanced users, try to strike a balance between too much explanation and too little.

Code Snippets

Use the syntaxhighlight tag for sections of code. There is an option to use line numbers:

<syntaxhighlight lang="javascript" line="1"></syntaxhighlight>

<syntaxhighlight lang="javascript"></syntaxhighlight>

The formatting will look like these examples:

1 var BUTTERFLY_GRAVITY = 0;//-0.06;
2 var BUTTERFLY_FLAP_SPEED = 1.0;
3 var BUTTERFLY_VELOCITY = 20; /*butterflies should be zooming around with you now!*/
4 var DISTANCE_IN_FRONT_OF_ME = 1.0;
5 var DISTANCE_ABOVE_ME = 1.0;
var BUTTERFLY_GRAVITY = 0;//-0.06;
var BUTTERFLY_FLAP_SPEED = 1.0;
var BUTTERFLY_VELOCITY = 20; /*butterflies should be zooming around with you now!*/
var DISTANCE_IN_FRONT_OF_ME = 1.0;
var DISTANCE_ABOVE_ME = 1.0;

For code in text, use <code></code> tags. For example:

isKnownID returns true if the client knows the true identity of the entity.

For functions in the text, refer to the function name with parentheses, for example: functionName(). (The parentheses are preferred as they indicate that it is a function call rather than a variable name.)

Content

Limit page content to one major topic per page, where possible. You can always link to other relevant articles.

Grammar and Punctuation

For general grammar and punctuation, follow the The Chicago Manual of Style. A list a preferred spellings can be found in the Word List.

Links

Use wiki markup link format:

  • For links to other articles: [[Explore]] will turn into Explore.
  • For links to sections in specific articles: [[Explore#Look_Around]] or [[Explore#Look Around]] will both work because the wiki will automatically read the spaces in the link as underscores. They will look like this: Explore#Look_Around Explore#Look Around.
  • For links to sections in specific articles: [[Explore#Look_Around|look around Playa]] or [[Explore#Look Around|look around Playa]] will both work because the wiki will automatically read the spaces in the link as underscores. They will both look like this: look around Playa.
  • For links to a category without including the page in the category: [[:Category:Creator documentation]] will turn into Category:Creator documentation.
  • For links outside the wiki: [http://www.highfidelity.com High Fidelity Website] will turn into High Fidelity Website.

Next Steps

If your article leads logically to another page, include a 'Next Steps' section containing the appropriate link(s).

Notes

Notes should be formatted as follows:

''Note: This is a note and it uses italicized font.''

Referring to UI Elements

Use bold text and > to keep instructions brief and easy to read. Use the bold button in the editor or manually add '''wikimarkup bolding'''. For example:

Select File > Save.

Screenshots and Images

Although you should not add a screenshot for every step in your article, add screenshots as necessary to anchor the user. Upload the images to the wiki using descriptive, unique filenames and use the Description field in the upload file screen to fully describe what the image is showing.

After uploading, you can add images to the article using wiki markup. For example, this image will be displayed at 500 pixels wide with center alignment:

[[File:yourfilename.png|500px|center]]

Other alignment options include none (no text wrapping), left or right (with text wrapping).

For more advanced wiki markup formatting for images, see MediaWiki's Help:Images.

Word List

The wiki should use American English spelling. Additional preferred spelling and usage notes:

  • ID, IDs - Do not use lower case. For example: An action ID or entity ID is the unique number associated with an action or entity.
  • FBX
  • Interface - Capitalize and do not use the definite article. For example: Using Interface, you can...
  • JavaScript - mixed case capitalization except within the syntaxhighlight tag for identifying lang
  • JPG
  • Marketplace (not The Market)
  • OBJ
  • PDF
  • ray casting
  • Sandbox - Capitalize and do not use the definite article. For example: Using Sandbox, you can...
  • Stack Manager: Capitalize and do not use the definite article. For example: Using Stack Manager, you can...
  • URL