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 (noun or adjective), add on (verb)

Not addon.

Asset Viewer

Capitalize each word.

assetViewer{}

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, and 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.

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?)

daBuild

daEditor

Dagor Engine

Capitalize each word.

daNetGame

daNetGame-based, daNetGame-like

dynmodel

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

ECS

All caps. Expand the abbreviation on first mention.

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 (adjective)

Not 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.

login (noun or adjective), log in (verb)

Not log-in.

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 (noun), plug-in (adjective), plug in (verb)

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.

rendinst

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

screenshot

Not screen shot.

sign-in (noun or adjective), sign in (verb)

sign-out (noun or adjective), sign out (verb)

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 on how to capitalize specific words, see Word List.

Capitalize Product Names

See also

For more information on 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 works or 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)

  Graphical User Interface (GUI)

  eXtensible Markup Language (XML)

Commonly Accepted Abbreviations

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

• API

• LOD

• FPS

• File formats such as PNG, JPEG, or OBJ

• Units of measurement like MB, GB, or TB

• URL

• GPU, CPU, RAM

Articles

Use 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.