Style Guide

This page covers the voice, tone, and formatting conventions for all MK.IO and Beam documentation.

Voice & tone

• Write in second person ("you") and present tense.
• Be professional, clear, and confident. Guide from a place of expertise without talking down to the reader.
• Keep the tone instructional and straightforward — the reader is here to get something done.

Plain language

• Use simple, everyday words. Avoid jargon unless the term is necessary for the reader to complete a task.
• Define acronyms and technical terms on first use. For example: "Video on Demand (VOD)".
• One sentence should express one idea. Aim for 10–20 words per sentence.
• Put the most important information first.

Active voice

Use active voice whenever possible. It is shorter and clearer.

Avoid past tense unless you are specifically describing a completed event.

Inclusive language

• Use gender-neutral language ("they/them" for hypothetical users).
• Avoid ableist terms ("sanity check" → "validation", "crippled" → "limited").
• Avoid culturally specific references or idioms that may not translate globally.

Formatting quick rules

Images

• Keep images to a minimum. Only include a screenshot when text alone cannot explain a UI action.
• Prefer annotated screenshots over decorative images.
• Always add meaningful alt text: ![Create asset dialog showing the name field](./images/create-asset.png).
• Store images next to the page file or inside /public/.
• Do not use images for text content, code, or tables.

Links

• Use root-relative paths for internal links: [Getting Started](/mkio/getting-started).
• Do not include the .mdx extension in links.
• For section anchors, use lowercase with hyphens: [Jump to upload step](/mkio/getting-started#uploading-content).

Code blocks

• Always specify a language tag (e.g. bash, json, http).
• Do not prefix terminal commands with $ or >.
• Keep code examples short and focused on the concept being explained.

Lists

• Use numbered lists for sequential steps.
• Use bullet lists for non-ordered items. Keep bulleted list items short. If possible, avoid including a Callout in a list item.
• Keep list items parallel in structure (all start with a verb, or all are noun phrases).
• Avoid nested bulleted lists. If the content demands it, favor a first level with numbers and a 2nd level with bullets.

Page titles

• Use a clear, concise title that tells the reader what the page helps them do.
• Prefer imperative verbs for how-to pages: "Create an asset", "Stream content".
• Prefer noun phrases for reference/concept pages: "Encoding transform presets", "Asset filters".

File and folder names

Properly naming files and folders is important, and those will appear in the URL of your article.

• Ensure that the whole URL reads well. For example: docs.mediakind.com/mkio/getting-started/account-setup-and-first-steps.
• All lowercase
• Separate words with a hyphen.
• If you rename a file or a folder, ensure all incoming links are updated. Be mindful of relative paths. (e.g. ../receiver/input.mdx)
• Only rename folders after careful consideration. Do not rename root folders.