Dagor Documentation Style Guide

About This Guide

This style guide outlines editorial guidelines for creating clear, consistent, and accurate technical documentation intended for software developers and other technical professionals. It is designed to ensure consistency across all documentation related to Dagor Engine.

This guide is the primary reference for creating Dagor Engine documentation. If the guidelines provided here do not cover specific scenarios, refer to the following editorial resources:

• Spelling: Merriam-Webster.

• Non-technical style: The Chicago Manual of Style Online.

• Technical style: Google developer documentation style guide.

Voice and Tone

Adopt a voice and tone that is professional yet approachable – clear, respectful, and free from slang or excessive informality. The goal is to sound like a knowledgeable guide who understands the developer’s needs, providing helpful insights without being overly formal or condescending.

While a conversational tone is encouraged, avoid writing exactly as you speak. Strike a balance between clarity and relatability to keep the content engaging but focused.

Avoid being overly entertaining or excessively dry. The primary purpose of the documentation is to convey information efficiently to readers who may be seeking answers under time constraints.

Keep in mind that the audience may include readers from diverse cultural backgrounds and varying levels of proficiency in English. Writing in simple, consistent language enhances readability and facilitates easier translation into other languages.

Word List

3ds Max

Always capitalize Max.

add-on vs. add on

Not addon.

Use add-on as a noun or adjective.

The game includes a new add-on for additional levels.

Use add on as a verb.

The developer plans to add on more content next update.

Asset Viewer

Capitalize each word.

Blender

Always capitalize.

BLK format

When referring to a format in general.

.blk files

When referring to specific files with the BLK format. File extensions are formatted with a code font.

Building Resources

Use Building Resources when referring to the title or heading.

Use resource building process (or similar) when describing the act of compiling resources.

button

You click on-screen buttons and mouse buttons, and press keys on the keyboard.

changelog

Not changeLog or ChangeLog.

Lowercase except at the beginning of a sentence, heading, or list item.

checkbox

Use check/uncheck for clear and specific checkbox actions.

Check the Enable Ray Tracing box to activate advanced lighting effects in your scene.

Uncheck the Enable Shadows box to disable shadow rendering and improve performance.

Avoid ambiguity by clarifying the checkbox’s effect.

Check the Dynamic Lighting box to apply real-time lighting changes during gameplay.

Enable the box for dynamic lighting. (Unclear: What does “enable the box” mean? Does it turn on the feature or just make the checkbox switchable?)

D3D, Direct3D, DirectX

Always capitalize.

daBuild

Retain the exact casing as defined by the development team. If possible, revise the sentence to avoid starting with a lowercase product name.

daEditor, daEditorX

Retain the exact casing as defined by the development team. If possible, revise the sentence to avoid starting with a lowercase product name.

daGI

Expand the abbreviation on first mention: Dagor Global Illumination (daGI).

Dagor Engine

Capitalize each word.

daNetGame

Retain the exact casing as defined by the development team. If possible, revise the sentence to avoid starting with a lowercase product name.

daNetGame-based, daNetGame-like

Not daNetGame based or daNetGame like.

daRG

Expand the abbreviation on first mention: Dagor Reactive GUI (daRG).

dynmodel

Lowercase except at the beginning of a sentence, heading, or list item.

ECS

All caps. Expand the abbreviation on first mention: Entity-Component-System (ECS). When expanded, capitalize each word and hyphenate to form a compound noun.

FAR

All caps.

gameobj

Lowercase except at the beginning of a sentence, heading, or list item.

ID

Not Id or id, except in string literals or enums.

Impostor Baker

Capitalize each word.

in-game vs. in game

Not ingame.

Use in-game as an adjective.

View your in-game settings.

Use in game only when in is a preposition followed by the noun game.

That feature isn’t available in game.

internet

Lowercase except at the beginning of a sentence, heading, or list item.

LOD, LODs

All caps. Expand the abbreviation on first mention: Level of Detail (LOD).

login vs. log in

Not log-in.

Use login as a noun or adjective.

Enter your login credentials.

Use log in as a verb.

You need to log in to view your achievements.

microdetails

Not micro-details.

Lowercase except at the beginning of a sentence, heading, or list item.

parent-child or parent/child

Not parent – child or parent—child.

per

To express a rate, use per instead of the division slash (/).

please

Do not use please in the normal course of explaining how to use a product.

Use please only when you’re asking for permission or forgiveness. For example, when what you’re asking for inconveniences a reader, or suggests a potential issue with a product.

plugin vs. plug-in vs. plug in

Use plugin as a noun.

This audio plugin improves spatial sound processing.

Use plug-in as an adjective.

Enable the plug-in module for particle effects.

Use plug in as a verb.

Please plug in the VR headset to continue.

pop-up window, pop-up menu

Use pop-up window to describe a window that appears over the main interface to provide additional information, request input, or display notifications.

Use pop-up menu to describe the menu that appears when a user right-clicks an item.

prebuilt

Not pre-built.

prefab

Lowercase except at the beginning of a sentence, heading, or list item.

read-only

Not read only.

real-time vs. real time

Use real-time with a hyphen when used as an adjective:

real-time updates, real-time communication

Use real time without a hyphen when used as a noun.

The system operates in real time.

rendinst

Lowercase except at the beginning of a sentence, heading, or list item.

riExtra

Lowercase except at the beginning of a sentence, heading, or list item. Always capitalize Extra.

screenshot

Not screen shot.

sign-in vs. sign in

Use sign-in as a noun or adjective.

The sign-in process includes two-factor authentication.

Use sign in as a verb.

Players must sign in with their account before accessing online services.

sign-out vs. sign out

Use sign-out as a noun or adjective.

The sign-out option is in the settings menu.

Use sign out as a verb.

The game automatically signs out inactive users.

subdirectory

Not sub-directory.

toolkit

Not tool-kit or tool kit.

utilize

Do not use utilize when you mean use.

Use utilize or utilization when referring to the quantity of a resource being used.

vromfs

Lowercase except at the beginning of a sentence, heading, or list item.

War Thunder

Capitalize each word.

War Thunder-based, War Thunder-like

Not WarThunder-based or War-Thunder-based.

Product Names

This section describes how to use product names.

• Capitalize Product Names. When you write about any product, follow the official capitalization for the names of brands, companies, software, products, services, features, and terms defined by companies and open source communities. If an official name begins with a lowercase letter, then put it in lowercase even at the start of a sentence. But it’s better to revise the sentence to avoid putting a lowercase word at the start, if possible.

• Feature Names. When you write about a feature, don’t capitalize it unless the name is officially capitalized. If you’re unsure, follow the precedent that’s set by other documents that describe the feature.

• Shorten Product Names. Use the full trademarked product name. Don’t abbreviate product names, except in cases where you’re matching a UI label.

• Use The with Product Names. Use the with product names when referring to specific instances, roles, or modified versions. Avoid the when the name functions as a standalone proper noun or appears in branding.

  See also

  For more information, see Use The.

Text Formatting

Text-formatting summary for many of the general conventions covered elsewhere in the style guide.

Bold

Use bold formatting, for UI elements, run-in headings and in special cases to emphasize important phrases in a sentence.

Italic

Use italics formatting, when drawing attention to a specific word or phrase, such as when defining terms or using words as words.

Underline

Do not underline.

Code Font

Use code font for:

• Filenames, filename extensions, and paths

• Folders and directories

• Parameter names and values

• Placeholder variables

• Text input

• Console output

• Key names and mouse button labels

• Code in text, inline code, and code samples

Items to put in ordinary (non-code) font:

• IP addresses

• URLs

• Domain names

• Names of products, services, and organizations

Font Type, Size, and Color

• Do not override global styles for font type, size, or color.

• Use different text colors in examples only when it is the most effective method to clarify a concept.

Other Punctuation Conventions

• Do not use ampersands (&) as conjunctions or shorthand for and. Use and instead.

• Use & in cases where you need to refer to a UI element or the name that uses &.

• Do not use an exclamation mark.

Units of Measurement

• Put a nonbreaking space   between the number and the unit.

  120 GB

  120GB

  5 m

  5m

• If the unit of measure is money or percent or degrees of an angle, do not use a space.

  $20

  50%

  90°

• In a range of numbers, repeat the unit for each number. Use the word to between the numbers, rather than a hyphen.

  0° to 90°

  0-90°

  5 m to 10 m

  5-10 m

Headings

• Each file should contain a single topic article.

• The article may have one top-level heading, and subsequent headings should follow a sequential order, without skipping any levels.

• If the main heading of an article is defined using other tools, section headings within the file should begin at the second level.

Capitalization

Follow the standard capitalization rules for American English. Additionally, do the following:

• Do not use unnecessary capitalization.

• Do not use all-uppercase, except in the following contexts: in official names, in abbreviations that are always written in all-caps, or when referring to code that uses all-caps.

• Do not use camel case, except in official names or when referring to code that uses camel case.

  See also

  For information about how to capitalize specific words, see Word List.

Capitalization of Product Names

See also

For more information about how to capitalize product names, see Product Names.

Capitalization in Titles and Headings

• In document titles and headings, use title case. That is, capitalize the first and last words of the title, as well as all major words such as nouns, pronouns, verbs, adjectives, adverbs, and proper nouns.

• Articles (a, an, the), conjunctions (and, but, or), and prepositions with fewer than four letters are not capitalized unless they appear as the first or last word of the title.

Capitalization in References to Titles and Headings

• When referencing any title or heading from a document that follows this guide, use title case.

• For titles or headings from sources that do not follow this guide, retain the original capitalization.

Capitalization for Figures and Tables

• Use sentence case for labels, callouts, and other text in images and diagrams.

• Use sentence case for all the elements in a table: contents, headings, labels, and captions.

Capitalization and End Punctuation

Numbered, Lettered, and Bulleted Lists

Start each list item with a capital letter, unless case is an important part of the information conveyed by the list.

End each list item with a period, except in the following cases:

• If the item consists of a single word.

• If the item doesn’t include a verb.

• If the item is entirely in code font.

• If the item is entirely link text or a document title.

Recommended:

The interface is organized into three main panels:

1. Control Panel

2. Properties Panel

3. Viewport Settings Panel

Recommended:

To export an animation, follow these steps:

1. Ensure Visibility.

2. Export Settings.

3. Add Note Tracks.

Recommended:

Environment textures:

• envi snapshot

• background texture

• paint details texture

• reflection texture

Description Lists that Use Run-in Headings

• Start the run-in heading with a capital letter.

• End the run-in heading with a period or a colon, but be consistent within the list.

• You can decide whether to bold the punctuation that ends the heading based on factors such as on-page consistency.

• For the descriptions that follow the punctuation, capitalize the first letter as follows:

  • If the text follows a period, start the text with a capital letter.

  • If the text follows a colon, start the text with a lowercase letter.

• To end the descriptive text, punctuate as follows:

  • If the description follows a period, end the description with a period.

  • If the description follows a colon, do one of the following:

    • If the description is a list of items or short phrases without verbs, do not include a period.

    • If the description includes a verb or expresses a standalone thought, end the description with a period.

• Do not use a dash to set off a description from an item in a description list.

Recommended:

This property defines how the object interacts with landscape collision:

• Ignore Collision: the object’s height matches its pivot point.

• Place Pivot: the pivot point is placed directly on the collision surface.

• Place Pivot and Use Normal: the object’s pivot aligns to the normal of the landscape.

• Place 3-Point (bbox): a bounding box is created around the object.

• Place Foundation (bbox): all points of the bounding box base align with the collision surface.

Recommended:

There are three types of builds:

• Full Build. Builds all resources.

• Partial Pack Build. Builds the specific pack containing the resource you need.

• Partial Package Build. Builds an entire package.

Capitalization in Hyphenated Words

Capitalize all main words in hyphenated terms in titles and headings.

High-Level Architecture Overview

High-level architecture overview

Exceptions:

• Hyphenated Words with Prefixes: do not capitalize prefixes in hyphenated words unless they start the title or heading.

  Re-evaluation of System Processes

  Re-Evaluation of System Processes

• Hyphenated Words Beginning with Single Letters: do not capitalize the single letter at the start of a hyphenated term unless it begins the title or heading.

  X-ray Analysis Results

  X-Ray Analysis Results

• Hyphenated Articles, Prepositions, and Coordinating Conjunctions: do not capitalize hyphenated articles, prepositions, or coordinating conjunctions unless they start the title or heading.

  End-to-end Encryption Setup

  End-To-End Encryption Setup

Capitalization and Colons

Use a lowercase letter to begin the first word of the text immediately following a colon unless the text falls into one of the exceptions.

The system processes data in three phases: input, processing, and output.

The system processes data in three phases: Input, processing, and output.

Exceptions:

• Proper Noun: capitalize the first word if it is a proper noun.

• Heading: capitalize the first word if the text following the colon is a heading.

• Quotation: capitalize the first word if the text following the colon is a quotation.

Language

Abbreviations

Key Guidelines for Abbreviation Usage

• Use standard acronyms that improve readability and save the reader time.

• Spell out abbreviations on first reference.

• Avoid using specialized abbreviations that may be unfamiliar to your audience unless they are clearly defined.

When to Spell Out a Term

• When an abbreviation is likely to be unfamiliar to the reader, spell it out upon first mention and include the abbreviation in parentheses immediately afterward. Italicize both the spelled-out term and its abbreviation.

• For all subsequent mentions of the term, use only the abbreviation.

• Capitalize the letters which are used directly in the abbreviated form.

• If the first mention of an abbreviation occurs in a heading or title, it is acceptable to use the abbreviation directly. Then, spell out and define the abbreviation in the first paragraph following the heading.

  Level of Detail (LOD)

  Artificial Intelligence (AI)

  Game Engine Architecture (GEA)

Commonly Accepted Abbreviations

The following abbreviations are widely recognized and generally do not need to be spelled out:

• API

• CPU, GPU, RAM

• FPS

• File formats such as PNG, JPEG, or OBJ

• GUI, UI

• Units of measurement like MB, GB, or TB

• URL

Articles

Using The

Using the with product names in documentation depends on whether the product name is treated as a proper noun or a general noun phrase.

When to Use The

• Generic References. Use the when referring to a specific instance, feature, or role of the product.

  The Dagor Engine renderer supports advanced real-time lighting techniques.

• Functional Contexts. Use the when describing how the product functions or interacts in a specific scenario.

  The Dagor Engine physics module excels in simulating large-scale destructible environments.

• With Modifiers. Use the when the product name is modified by an adjective, clause, or descriptive element.

  The enhanced Dagor Engine API streamlines shader development.

When Not to Use The

• As a Standalone Proper Noun. Avoid the when the product name stands alone as a proper noun.

  Dagor Engine integrates seamlessly with custom asset pipelines.

• In Branding or Titles. Do not use the when the product name appears in a title or branded term.

  Explore new possibilities with Dagor Engine 6.

Exceptions:

• Some product names may inherently include the due to branding or established usage.

• In lists or general overviews, omitting the is acceptable for brevity:

  Features include GPU-driven rendering, multi-threaded processing, and terrain optimization.

Omitting Articles in Headings and Titles

It is acceptable to omit articles (such as a, an, and the) in headings and titles for brevity and clarity. This helps maintain a clean and concise presentation of content, especially when space is limited or when the title needs to be more direct.

Linking

Cross-references

Cross-references are typically used to link to nonessential information that enhances the reader’s understanding. Whenever possible, provide contextual help rather than redirecting the reader elsewhere.

Follow these guidelines when creating cross-references to other documents:

• When referring to a document that adheres to this style guide, place the reference in a separate paragraph using the documentation builder tools. If you are referencing the same document from multiple locations within the original document, it is acceptable to insert the link directly within the text, without placing it in a separate paragraph.

• When referencing third-party tools or products, linking to the relevant site is acceptable. Ensure that any linked site is reputable, reliable, and of high quality.

• Do not link to content that is behind a paywall or otherwise restricted. All linked materials must be freely accessible to the reader, with no additional access requirements.

Formatting Cross-references

• Introduce the link with the phrase For more information, see or For more information about…, see.

• Use see and about instead of read and on when referencing links and cross-references.

  Recommended:

  See also

  For more information about how to set up and start developing with the Dagor Engine, see Getting Started with Dagor.

  For more information on assets, read Introduction to Assets.

  See this article.

  Click here.

• When referencing a document title or heading from a document that follows this guide, use the full document title in title case.

  Recommended:

  See also

  For more information, see Capitalization in References to Titles and Headings.

• If the link points to a downloadable file, clarify this in the link text and specify the file type and size if the file is large.

  Recommended:

  See also

  For more information about Dagor ECS, download Anton Yudintsev’s video lecture Gameplay-Architecture-and-Design.mp4, 3.65 GB.

• When including a cross-reference as a link, avoid putting the link text in quotation marks.

  Recommended:

  See also

  For more information, see BLK File Format.

  Not recommended:

  See also

  For more information, see “BLK File Format”.

• Do not use a URL as link text. Instead, use the page title or a description of the linked page. An exception may be made for certain legal documents (e.g., Terms of Service), where URLs can be used as link text.

• If the link includes an abbreviation in parentheses, include both the full form and the abbreviation in the link text.

  Physically based rendering (PBR)

  Physically based rendering (PBR)

• If the text includes a command or a code element typically represented in code font, include a description of the code element in the link text, unless it would be redundant or awkward.

  To set the current camera direction, run the camera.dir command.

  The daEditor supports the list, help, and clear console commands.

  To configure the environment settings, run the envi.set command.

• Do not place links in section headings.

• Do not use images as links.

Links to Sections on the Same Page

When linking to another section on the same page, indicate that the link will navigate to a different section of the same document.

Recommended:

See also

For more information, see the Formatting Cross-references section of this document.

Links to Sections on Another Page

When linking to a section on another page, format the link the same way as a standard cross-reference.

If the section title on the destination page is identical to one on the source page, provide additional context for clarity.

Recommended:

See also

For more information, see Basic concepts in “Dagor ECS”.

Punctuation with Links

When punctuation appears immediately before or after a link, place the punctuation outside the link tags where possible.

For more information, see Getting Started with Dagor.

For more information, see Getting Started with Dagor.

Punctuation

Hyphen, Dash, and Minus Sign

Em dashes (—), en dashes (–), hyphens (-), and minus signs (−) are distinct and should be handled accordingly, with attention to their proper function.

Hyphen (-)

Use the hyphen to join words or split them at the end of a line.

General Guidelines

Hyphenation depends on context, readability, and conventions:

• Position: Does the term come before a noun or after a verb?

• Clarity: Will the sentence be unclear without a hyphen?

• Rules: Some terms must always or never be hyphenated, regardless of other factors.

Exceptions are common. If unsure, check these sources in order:

1. Existing documentation conventions.

2. This style guide’s Word List.

3. Merriam-Webster dictionary.

Use hyphen for:

• Compound Noun Modifiers

  Use a hyphen between two or more words that work together to modify a noun before the noun, especially when:

  • Clarity requires it

    floating-point texture

    frame-by-frame playback

    up-to-date build

    frame by frame playback

  • One word is a participle (-ed or -ing)

    GPU-accelerated path

    baked-in lighting

    left-aligned text

    The text is left aligned. (no hyphen after noun)

  • The modifier includes a number or letter

    3-point lighting

    5-stage pipeline

    Y-based sorting

  Avoid hyphens when the meaning is clear without them or the modifier comes after the noun.

  If a modifier has more than two words, try to rephrase. If rephrasing isn’t possible, hyphenate as needed for clarity.

  Exceptions

  Don’t hyphenate -ly adverbs unless clarity suffers:

  Publicly available assets

  Highly detailed mesh

  Visually rich environment

  Poorly-lit scene

  Don’t hyphenate terms that are commonly unhyphenated:

  A managed instance group

  A machine learning model

  For number + unit modifiers, skip the hyphen unless needed:

  60 FPS animation

  200 GB disk

  See also

  For more information, see Units of Measurement.

• Suspended Compound Modifiers

  Avoid suspended compound modifiers, such as:

  CPU- and GPU-bound tasks

  left- and right-aligned elements

  These constructions can reduce clarity. Instead, spell out the full phrase:

  CPU-bound and GPU-bound tasks

  left-aligned and right-aligned elements

  If you must use a suspended modifier due to space constraints (e.g. in UI or diagrams), include a hyphen after the first word and a space:

  mouse- or keyboard-based input

  Don’t use suspension when dealing with simple one-word adjectives:

  high and low settings

  high- and low settings

• Compound Numerals and Fractions

  Use hyphens in compound numerals and fractions when they function as adjectives.

  a thirty-second frame

  a one-third resolution scale

  a sixty-four-bit architecture

  Don’t hyphenate if the fraction or number is used as a noun:

  The frame took one third of a millisecond.

  Support for sixty four bit is deprecated.

  Support for sixty-four-bit is deprecated.

• Compound Nouns

  It’s preferable to use the closed (one-word) form for compound nouns whenever it’s standard in engine or toolchain usage:

  renderpass, framebuffer, toolchain

  If Merriam-Webster lists a spaced or hyphenated form but the closed version is commonly used in game engine-related area or codebase, use the closed form.

  Exceptions

  Use hyphens or spaces for established terms:

  multi-pass rendering, debug layer, camera rig, physics material

  Some words change form by usage:

  set up (verb), setup (noun)

  log in (verb), login (noun)

  For compound units of measurement or units that multiply, use hyphens:

  120 render-thread-hours

  10 AI-agent-hours

  5 vCPU-hours

  40 person-hours

• Prefixes

  Avoid creating new, nonstandard words by simply attaching a prefix to an existing word. If the resulting form isn’t widely recognized, rephrase for clarity.

  reinitialize the renderer

  non-player entity

  reinit renderer

  noninteractiveable UI

  Use a hyphen between a prefix and a stem word:

  • If a confusing or ambiguous word results without the hyphen:

    re-sign (sign again) vs resign (quit a job)

    co-op (cooperative) vs coop (a cage for chickens)

  • If the stem word begins with a capital letter:

    non-XML, pre-IPv6

  If the prefixed word is listed in Merriam-Webster or the Word List, you can use it. When in doubt, rewrite or hyphenate to improve readability.

  In general, don’t include a hyphen after the following prefixes unless omitting the hyphen could confuse the reader.

  • auto-

  • co-

  • cyber-

  • exa-, giga-, kilo-, mega-

  • inter-, intra-

  • macro-, micro-, mono-

  • non-

  • omni-

  • pre-

  • re-

  • sub-

  • tera-

  • un-, uni-

En Dash (–)

Don’t use en dashes.

Use a hyphen or the word to instead.

For ranges, use:

60–120 FPS write as 60 to 120 FPS

GPU-bound tasks 1–4 write as tasks 1 to 4

Avoid using dashes with spaces (–, —, or -) to separate labels from descriptions. Use a colon or period instead.

Frame timing: Controls update frequency.

Example: Use renderpass to group draw calls.

Frame timing - Controls update frequency

Example — Use renderpass to group draw calls

Em Dash (—)

Don’t use em dashes.

Em dashes can cause inconsistency in formatting, reduce readability in technical contexts, and create issues in code snippets, tooling, and localization.

Instead, use:

• A colon (:) to introduce explanations or definitions.

• A hyphen (-) for compound terms.

• The word to for ranges.

  Renderpass: Defines a sequence of draw calls

  Use a real-time rendering pipeline

  Set frame rate to 60 to 120 FPS

Why we avoid en/em dashes?

To keep formatting consistent and machine-friendly, Dagor documentation does not use en (–) or em (—) dashes. Dashes can cause issues with readability, localization, and rendering across platforms. Instead, we prefer clear and stable alternatives:

• Use a colon (:) to introduce definitions or descriptions.

• Use the word to for numeric ranges.

• Use a hyphen (-) for compound terms.

  LOD: Level of Detail system

  60 to 120 FPS

  GPU-bound rendering

This approach improves clarity and avoids formatting issues in tools, editors, and translations.

Minus Sign

Use the minus sign (−) only for subtraction and negative numbers in formulas or code.

Do not substitute an en dash (–) for the minus sign, as it can cause confusion and accessibility issues.

Health = MaxHealth − DamageTaken

Velocity = −9.8 m/s² (gravity)