Kinetic Data Documentation Style Guide

This Documentation Style Guide is meant to:

• Standardize the terminology we use when talking about the Kinetic Platform.

• Explain the reasoning behind certain phrases, sentence structures, or formatting choices.

• Discuss the different methods we use to give our documentation an overarching “Kinetic voice”.

Style Guidelines

In most cases, we follow the rules outlined in the Microsoft Style Guide. The Kinetic Data Style Guide focuses on:

• Topics that are not addressed in the Microsoft guide

• Situations where we do not follow Microsoft practices

• Addressing commonly-discussed style topics so you don’t have to search the Microsoft guide for them

You can send questions, feedback, or suggestions for improvement to [e-mail].

Accessibility

Accessibility could have an entire style guide of its own, but here are some major considerations:

• Provide a clear description to go with any images. Saying “as shown in the image below” without describing the image makes the example unhelpful for those with impaired vision.

• Provide alt text for non-text elements for users that rely on a screen reader.

• Include captions for any video content. KD has access to a transcription tool you can use to create captions.

Referencing Kinetic Components

When referencing Kinetic components (for example, Kinetic Forms or Kinetic Kapps), use “Kinetic [Component]” on the first reference, capitalizing both words. On subsequent references, do not begin with “Kinetic” and use lowercase for the component.

Example: The Kinetic Workflow component can retrieve and update information from numNerous other systems, perform calculations using Ruby, and dynamically determine process steps. The workflow process takes over once a Kinetic Form is submitted.

Exception: Do not use this format when referring to teams or users.

Capitalization

Never capitalize:

• kinops

• File extensions (.pdf, .exe, etc.)

Formatting

Bold: Use bold font for the following situations:

• Bulleted list lead-ins

• Database names

Grammar and Parts of Speech

• e.g.: Use “for example” instead to avoid confusion/misuse.

• i.e.: Use “that is,” (including the comma) instead to avoid confusion/misuse.

• In vs. within: When used as prepositions, both are used to describe spatial relationships. The difference is whether the spatial relationship is definite (in) or has boundaries (within). When in doubt, use “in”.

• In vs. on: Use “on” as a preposition with the terms below. Otherwise, use “in”.

  • Menus

  • Tabs

  • Taskbar, toolbar, ruler, and desktop

  • Disks, in the sense of a program being on a disk

  • Networks

  • Hardware platforms

  • The web

• That vs. which: Use “that” at the beginning of a clause that’s necessary for the sentence to make sense. Don’t put a comma before “that”.

  • Include “that” even if the sentence is clear without it. It helps to clarify the sentence structure.

  • Use “which” at the beginning of a clause that adds supporting or parenthetical information. If you can omit the clause and the sentence still makes sense, use “which”, and put a comma before it.

• Use vs. utilize: If you’re referring to something’s intended purpose, use “use”. If something can be used in a way other than its original purpose and you’re referring to the alternative way, use “utilize”.

  • Example: You “use” cat litter in litter boxes, but you can also “utilize” it for better traction when driving in icy conditions.

Images

• Provide a brief description of the image/its purpose to use as alt text.

• When adding images to the Doc Library, select the Border option to automatically assign a border with the correct properties.

• For other situations, you can manually add a 3px border using RGB value #ced0d2.

Lists

Bulleted vs. numbered lists: Use numbered lists for steps that need to be completed in a specific order. Otherwise, use a bulleted list.

Punctuation

• Do not replace “and” with an ampersand “&”.

The exception to this rule is website copy, which uses ampersands to improve SEO results.

• Use a single hyphen (-) when linking words (third-party) or indicating a range (Monday-Friday). Don’t add spaces around a hyphen.

• Use an em dash (—) to set off a parenthetical phrase with more emphasis than parentheses provide. Don’t add spaces around an em dash.

• Avoid using semicolons when possible. Use an em dash (—) or split the sentence into two or more sentences.

Voice

Our communications should be friendly, informal, and approachable. Here are some general guidelines:

• Use first-person (“you,” “we”) language whenever possible.

• Use active voice (have the subject of the sentence act).

  • Do this: “You can download the program update from…”

  • Not that: “The program update can be downloaded from…”

• Use contractions; they’re more energetic and conversational.

• Keep things brief. If you can explain in 5 words, don’t use 10.

• Always consider your audience. Most of what we write is for technically-minded people, but we should still try to keep things as simple as possible.