Style Guide

High Fidelity Style Guide

Style Guides help establish a consistent voice for High Fidelity. It makes it easier for users to read, understand, and use High Fidelity effectively.

Content is useful and meaningful when it is engaging, precise and coherent. This style guide contains basic guidelines for you to follow while writing for High Fidelity, to make the learning process for a reader seamless and consistent.

Using a consistent voice and tone also helps us represent a single voice, a voice that promotes sharing experiences in virtual reality.

This Style Guide uses concepts from the Microsoft Manual of Style (4th Ed.) and The Chicago Manual of Style.

Consistency

Consistency is the key to better learning. By keeping the structure, word choices and voice consistent, a reader will find it easier to absorb new information and concepts quicker.

We’ve created four templates for any submissions to High Fidelity. The templates will help you structure your writing and keep it consistent with the rest of the documentation. Keep in mind that there is flexibility when it comes to following these templates. You are free to omit certain sub-headings and categories if your work will not contain such information. You can access the templates here.

If your content cannot be supported by these templates, please contact docs@highfidelity.io.

Voice & Tone

High Fidelity Inc. is an open-source project for shared social virtual reality (VR) experiences. Our users can come from any background, but they all will share an interest in creating and exploring social VR spaces. It is this openness and creativity that is reflected in the voice and tone of the company. While writing pages on important technical information, keep in mind that most readers will want to get to the details fast. Keep the fluff out, but the light informal tone in.

Sound polite and encouraging. It’s natural to forget sometimes in the midst of our own busy lives, but an error message or help prompt that sounds polite and encouraging could buoy a user facing technical difficulties.

There are no hard and fast rules when it comes to contractions or other aspects of writing. You’re free to write informally and sound like you are talking to your reader. The only thing to keep in mind is that readers may come from different parts of the world and may not understand certain colloquial phrases or terms. They might also not understand or take offense to your jokes. It’s best to be sensitive when writing with humor (if you’re feeling humorous) and stick to common terms used the world over.

Language

Use everyday, common words and try to keep things simple. Shorter and simpler words sound more conversational and are easier to read and comprehend. It also makes it easier to translate content for a non-native English speaker.

Avoid jargon and use words that are frequent in everyday speech. If you do have to use jargon, make sure you define it at the beginning to avoid confusion.

Do not make generalisations about people, cultures, religions or countries or use culturally sensitive terms.

Use gender-neutral words and avoid racial, cultural, and sexual stereotypes.

Sentence Structure and Grammatical Choices

You can follow some basic guidelines to make your writing clear and coherent. Some of them are:

  • Use characters as subjects and actions as verbs: This helps keep your sentences shorter and simpler.

    For example: This avatar created by you can now be exported to High Fidelity.

    Can be changed to: You can now export the avatar you created to High Fidelity.

  • Remove unnecessary words that don’t add any meaning to your sentence such as really, very, just etc.

  • Avoid long introductory phrases and get to what you’re talking about quickly.

    For example:

    Since most developers take some time to complete the initial setup before starting work, we decided to give them a week’s time before they started training.

    Can be changed to: We decided to give new developers a week’s time to settle in before training, since most of them take time to complete the initial setup.

  • Use active voice instead of passive voice: This has the advantage of making writing straightforward and clear.

  • When writing instructions, use the imperative mood. This means that give instructions as a command or request to keep them short.

    For example: Select Reset Avatar Settings to undo your changes.

  • Use second person to sound conversational.

Punctuation

  • Use exclamation points and semi-colons sparingly.
  • Use the serial (Oxford) comma.
  • Read your writing aloud to yourself and check if you have placed your commas where you would naturally pause while speaking.

Template Structure

All the templates contain a similar structure with a few differences depending on the subject. But certain guidelines apply for all of them:

  • All headings must be in title-case.
  • All articles must contain an overview that details the goal of the article or page and contain a brief overview of the entire topic.
  • Whenever possible, use bulleted lists for easy scanning.
  • Write in short chunks, making your paragraphs readable.
  • All sentences part of bulleted lists must end with a period.
  • Ensure that you always link relevant parts of your text to updated docs in High Fidelity.