Official Docs Format Guide

Department

#	Section
1	Purpose
2	File Location & Naming
3	Document Structure
4	Content Formatting Rules
5	Standard Sections
6	Asana Card Templates
7	Cross-References & Links
8	Authoring Checklist

Purpose

This guide defines the exact format and structure that all Kiluth Official Documents must follow. It ensures consistency, readability, and compatibility with our documentation system (Quartz wiki).

Outcome
Every document follows the same structure, making it easy to navigate, maintain, and translate.

File Location & Naming

Location Pattern

All documents live in: kiluth-docs/content/<locale>/<department>/<Document Name>/index.md

#	Component	Example	Notes
1	Locale	`en`, `th`, `cn`, `es`, `jp`	Locales are configured in `quartz/i18n/locales.ts`. Currently: `en` (English), `th` (Thai). Future locales will be added as needed.
2	Department	`account-management`, `delivery`, `hr`, `technology`, `finance`, `legal`, `marketing`, `creative`	Department folder names use kebab-case
3	Document Name	`Scope Definition & Price Assessment Guideline`	Folder name matches document title exactly (spaces, capitalization preserved)
4	File	Always `index.md`	Each document folder contains a single `index.md` file

Naming Convention

Document folder names match the document title exactly (spaces, capitalization preserved)
Use title case for document names (e.g., “Onboarding Guideline”, not “onboarding guideline”)

Document Structure

Top-of-File (Required Order)

Every document must start with this exact sequence:

#	Element	Format
1	YAML frontmatter	`---` `title: Document Title` `---`
2	Blank line	(empty line)
3	H1 heading	`# Document Title` (repeats the title)
4	Blank line	(empty line)
5	Department block	`Department` `<blank line>` `Department Name`

Example:

---
title: Onboarding Guideline
---
 
# Onboarding Guideline
 
Department
 
[[en/hr/|HR]]

Table of Contents (Always Present)

#	Requirement
1	Always include a Table of Contents section
2	Use locale-appropriate heading: `## Table of Contents` (EN), `## สารบัญ` (TH), etc.
3	Use a 2-column table format
4	First column: `#` (or blank)
5	Second column: `Section` (EN), `ส่วนประกอบ` (TH), or appropriate translation for other locales

Example (English):

## Table of Contents
 
| # | Section |
| --- | --- |
| 1 | [Purpose](#purpose) |
| 2 | [Scope](#scope) |

Example (Thai):

## สารบัญ
 
| # | ส่วนประกอบ |
| --- | --- |
| 1 | [วัตถุประสงค์](#วัตถุประสงค์) |
| 2 | [ขอบเขต](#ขอบเขต) |

Note: When adding a new locale, translate “Table of Contents” and “Section” appropriately for that language.

Section Separators

Use horizontal rules (---) between major sections for visual separation.

Content Formatting Rules

Lists → Tables (House Rule)

Never use bullet points or numbered lists in content. Always convert them to tables.

#	Original	Converted To
1	Bullet list	Table with `#` column
2	Numbered list	Table with `#` column
3	Checklist items	Table with `☐` in cells

Example (before):

- Item 1
- Item 2
- Item 3

Example (after):

| # | Item |
| --- | --- |
| 1 | Item 1 |
| 2 | Item 2 |
| 3 | Item 3 |

Outcome Blocks

Use 1-column tables for outcome statements:

| __Outcome__ |
| --- |
| <one-sentence outcome> |

Thai equivalent:

| __ผลลัพธ์__ |
| --- |
| <หนึ่งประโยค> |

Decision Point Branching

Use 2-column tables for decision points:

Outcome	Action
Qualified	Proceed to handoff…
Not qualified	Record reason…

Thai equivalent:

ผลลัพธ์	การดำเนินการ
ผ่าน	ดำเนินการต่อ…
ไม่ผ่าน	บันทึกเหตุผล…

Standard Sections

Operating Model (Standard Text)

Every process document includes an “Operating Model” section with identical wording:

#	Operating Model
1	Asana is the system of record for work tracking, approvals, and handoffs.
2	Use checkpoints and decision points: don’t move forward until the previous step is “done”, and branches are explicit.
3	Handoff order: upstream defines handoff artifacts/exit criteria; downstream defines execution after handoff.

This text is identical across all documents (EN and TH).

Common Sections

Most documents include these sections (order may vary):

#	Section	When to Include
1	Purpose	Always
2	Scope	When boundaries need clarification
3	Definitions	When key terms need explanation
4	Operating Model	For process/workflow documents
5	Roles & Responsibilities	When multiple roles are involved
6	Step-by-Step Process	For workflow documents
7	Asana Card Templates	When handoffs require templates
8	Checklist	Optional (only when process has multiple handoffs/steps)

Asana Card Templates

When to Include

Include Asana card templates inline where handoffs occur (not in a separate section).

Format

Use a table format:

| | Asana Card Template |
| --- | --- |
| Title | [Task title] |
| Assignee | [Role/Department] |
| Description | Multi-line content here<br>• Bullet point<br>• Another bullet |

Description Field Formatting

#	Rule	Example
1	Use `<br>` for line breaks	`Line 1<br>Line 2`
2	Use `•` for bullets inside cells	`• Item 1<br>• Item 2`
3	Keep content concise and actionable

Cross-References & Links

Internal Document References

When referencing other Kiluth docs, use breadcrumb-style text:

See [[en/delivery/client-acceptance-uat-and-go-live-guideline|Client Acceptance (UAT) & Go-Live Guideline]].

Wiki Links

For internal wiki navigation, use wikilink syntax:

[[en/hr/onboarding-guideline|Kiluth Onboarding Guideline]]

Sign-Off Proof Labels

Standardized labels for sign-off proof links:

Language	Label Format
English	`Sign-off proof: [Link]`
Thai	`หลักฐานการ sign off: [ลิงก์]`

Authoring Checklist

Before finalizing any document, verify:

#	Checklist Item
1	☐ YAML frontmatter with `title:` present
2	☐ H1 heading matches title
3	☐ Department block formatted correctly (blank line between “Department” and name)
4	☐ Table of Contents present and complete
5	☐ All lists converted to tables
6	☐ Outcome blocks use 1-column table format
7	☐ Decision points use 2-column table format
8	☐ Operating Model section uses standard 3-bullet text (if applicable)
9	☐ Asana templates use `<br>` for line breaks
10	☐ Section separators (`---`) between major sections
11	☐ No bullet points or numbered lists in content
12	☐ Cross-references use breadcrumb style or wikilinks

Notes

English-first workflow: Finalize EN documents first, then translate to other locales using the same schema/layout
Locale configuration: Supported locales are defined in quartz/i18n/locales.ts. When adding a new locale (e.g., cn, es, jp), update that file first
Consistency over perfection: If unsure, match existing finalized documents (e.g., HR Onboarding Guideline)
Human-first writing: Follow the Creative department’s “Human-First Operational Writing Standard” for tone and style

Table of Contents