Skip to content

Excellent. Then we’ll lock this down properly so future pages don’t drift.

Below is a canonical DAQS documentation style guide you can drop straight into your knowledge base, for example as:

docs/reference/style_guide.md

This is written as a normative document, not a suggestion list. That’s intentional — style guides only work if they’re strict.

DAQS Documentation Style Guide

This document defines the writing style, structure, and formatting rules for all DAQS documentation.

Its goal is to ensure that all content is:

  • technically precise
  • consistent across pages
  • easy to read and maintain
  • scalable as the knowledge base grows

This guide applies to all Markdown files unless explicitly stated otherwise.

1. Content types

DAQS documentation distinguishes between three content types:

1.1 Introduction / Orientation

Purpose:

  • explain what the system is
  • explain why it exists
  • set expectations

Characteristics:

  • no deep technical detail
  • no exhaustive examples
  • conceptual language allowed

Location:

introduction/

1.2 Learning pages (primary focus)

Purpose:

  • teach concepts step-by-step
  • build understanding progressively
  • explain why and how

Characteristics:

  • ordered reading
  • minimal but complete examples
  • explicit constraints and rules

Location:

learning_path/

1.3 Reference pages

Purpose:

  • act as lookup documentation
  • answer specific technical questions
  • explain what something is

Characteristics:

  • no narrative
  • no step-by-step flow
  • exhaustive and precise

Location:

reference/

2. Page structure rules

2.1 Heading hierarchy

Each page must follow this structure:

  • Exactly one level-1 heading (#)
  • All main sections use level-2 headings (##)
  • Subsections use level-3 headings (###)
  • Never skip heading levels

Correct:

# Page title

## Main section

### Subsection

Incorrect:

# Page title

# Another title

2.2 Section ordering (learning pages)

Learning pages must follow this order where applicable:

  1. Title
  2. Short definition
  3. Why this matters (system perspective)
  4. Minimal working example
  5. Rules / constraints
  6. Common mistakes
  7. Mental model
  8. Rule of thumb
  9. Optional: What’s next

Not every page needs all sections, but ordering must be preserved.

3. Language and tone

3.1 Tone

The DAQS documentation tone is:

  • technical
  • direct
  • neutral
  • instructional

Avoid:

  • marketing language
  • conversational filler
  • rhetorical questions
  • motivational phrasing

Preferred:

“This is required because…”

Avoid:

“You might want to consider…”

3.2 Authority and certainty

Use normative language where appropriate:

  • must
  • required
  • cannot
  • always
  • never

Avoid hedging unless uncertainty is real.

3.3 Audience assumptions

Assume the reader:

  • understands basic BIM and Revit concepts
  • can read JSON / JSONata
  • is technical but not a DAQS internal developer

Do not assume:

  • knowledge of DAQS internals unless explicitly stated
  • prior reading unless referenced

4. Formatting rules

4.1 Paragraphs

  • Keep paragraphs short (1–3 sentences)
  • One idea per paragraph
  • Blank line between paragraphs

4.2 Lists

  • Use lists for factual information
  • Keep list items concise
  • Avoid nested lists unless necessary

Correct:

- Required field
- Optional field

4.3 Code blocks

  • Code blocks must be valid and minimal
  • Do not explain code inside code blocks
  • Explanations belong before or after

Correct:

$[type = "FamilyInstance"]

4.4 Horizontal rules

Use --- only to:

  • separate conceptual blocks
  • not as a visual spacer

If you feel the need to add many separators, reconsider section structure.

5. Examples and scope

5.1 Minimal examples first

  • Examples must demonstrate one concept only
  • Avoid real-world complexity on first introduction
  • Prefer clarity over realism

5.2 Explicit scope boundaries

Learning pages should state what they do not cover when relevant.

Example:

This page does not cover performance considerations or advanced filtering patterns.

6. Common mistakes sections

When documenting mistakes:

  • show the incorrect example
  • explain why it is incorrect
  • avoid shaming language

Correct:

This looks correct, but is invalid.

Avoid:

This is a stupid mistake.

7. Index pages (index.md)

Every folder must contain an index.md.

An index page must:

  • explain what the section is about
  • explain when to read it
  • explain what is not included

Index pages should be short and non-technical.

8. File naming conventions

8.1 Files

  • lowercase
  • snake_case
  • descriptive and specific

Correct:

symbol_vs_instance.md
singleton_vs_array_issues.md

Incorrect:

notes.md
stuff.md
revit_info.md

8.2 Folders

  • lowercase
  • snake_case
  • numbered only when representing learning order

Example:

01_getting_started

9. When to split content

Split a page if it:

  • explains both why and what in depth
  • grows beyond a single core concept
  • becomes hard to summarize in one sentence

Reference and learning content should not be mixed.

10. Enforcement principle

If content violates this style guide:

  • the content is considered incomplete
  • structure must be fixed before adding more detail

Consistency is more important than speed.

Status

This style guide is authoritative for the DAQS knowledge base.

Changes to this guide should be deliberate and rare.