Official Docs Format Guide

Department

Summary

Defines the exact format and structure for all Kiluth Official Documents: file location, document structure, content formatting (tables over lists), standard sections, task templates, and cross-reference style. Ensures consistency, readability, and compatibility with the documentation system.

	Section
1	Summary
2	Purpose
3	File Location & Naming
4	Document Structure
5	Content Formatting Rules
6	Standard Sections
7	Task Templates
8	Cross-References & Links
9	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: content/<department>/<document-name>/index.md

The folder name is a slug (kebab-case) derived from the document title.

#	Component	Example	Notes
1	Department	`account-management`, `delivery`, `hr`, `technology`, `finance`, `legal`, `marketing`, `creative`	Department folder names use kebab-case
2	Slug	`scope-definition-and-price-assessment-guideline`	Folder is kebab-case (lowercase, hyphens for spaces), derived from the document title. The document title in frontmatter and H1 stays human-readable title case.
3	File	Always `index.md`	Each document folder contains a single `index.md` file

Naming Convention

Document folder name is a slug: kebab-case, lowercase, spaces and special characters become hyphens (e.g. “Onboarding Guideline” → onboarding-guideline).
Document title (in frontmatter and H1) remains human-readable title case (e.g. “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](department/)`

Example:

---
title: Onboarding Guideline
---
 
# Onboarding Guideline
 
Department
 
[HR](hr/)

Table of Contents (Always Present)

#	Requirement
1	Always include a Table of Contents section
2	Include a Summary section after Department, before ToC
3	Use a 2-column table format
4	First column: `#` (or blank)
5	Second column: `Section`

Example:

## Summary
 
[2–3 sentence summary of the document]
 
## Table of Contents
 
|     | Section |
| --- | --- |
| 1 | [Summary](#summary) |
| 2 | [Purpose](#purpose) |
| 3 | [Scope](#scope) |

Section Separators

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

Content Formatting Rules

Language & Spelling (House Rule)

Kiluth Docs is written in English, American spelling.

#	Rule
1	Use American spelling: organize, authorize, standardize, summarize, behavior, center, license, canceled. Not organise, behaviour, centre, licence.
2	Keep a system’s own wording exactly as that system spells it, even when it differs. ERPNext’s document status is `Cancelled` — quote it that way; do not “correct” it.
3	The docs are English-only. If a client needs a Thai version of something, the owning department produces it as a per-client export, not as a second document in this repo.
4	Exception to rule 3: a doc may quote a non-English string it is prescribing — a Thai label people type into a tool, a Thai form name, a currency symbol. The document is still written in English; the quoted string is data. Do not translate these away.

Platform-Agnostic (House Rule)

Kiluth Docs describes process and policy, not the vendor of the week. Naming a platform dates the doc and misleads whoever reads it after the next migration.

#	Rule
1	Company-wide tools may be named — the systems everyone at Kiluth has access to and acts in: ERPNext / Kiluth Portal, Kiluth Tasks, Google Workspace (Drive, Chat, Gmail, Meet, Calendar).
2	Infrastructure and vendor platforms must not be named — cloud providers, CDNs, DNS providers, deploy controllers, hosting vendors and similar tooling used by a few specialists rather than the whole company.
3	Describe the capability, not the vendor: “the deploy controller”, “the DNS console”, “the provider’s destroy action”.
4	Platform-specific steps — the exact clicks, commands, URLs and pricing — belong in a runbook maintained by the owning department, not in Kiluth Docs.
5	The same applies to prices: state what is charged for and when, never how much. Amounts live on the ERPNext record for that client.

Example: instead of naming a vendor and its exact menu path (“VM → Settings → Destroy at ”), write “use the provider’s destroy action” and put the vendor’s steps in the runbook.

Lists → Tables (House Rule)

Prefer tables over bullet points and numbered lists. Convert a list to a table whenever the table earns its extra markup.

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

Convert when the list has four or more items, or is a checklist or process sequence. Those are the cases where a table genuinely helps someone scan under pressure.

Bullets may stay for a short aside of three items or fewer, and for lists nested inside another component (a table cell, a form-table Content block, a blockquote). Forcing a two-item aside into a table adds a header row and pipes for the same content — heavier, not clearer, and against the Human-First standard’s “minimal” and “shorter than it wants to be” principles.

When the two readings conflict, favour the one that is faster to read.

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

Decision Point Branching

Use 2-column tables for decision points:

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

Standard Sections

Operating Model (Standard Text)

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

#	Operating Model
1	Kiluth Tasks 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.

Common Sections

Most documents include these sections (order may vary):

#	Section	When to Include
1	Summary	Always (2–3 sentences after Department)
2	Purpose	Always
3	Scope	When boundaries need clarification
4	Definitions	When key terms need explanation
5	Operating Model	For process/workflow documents
6	Roles & Responsibilities	When multiple roles are involved
7	Step-by-Step Process	For workflow documents
8	task templates (inline)	At each handoff step where a task is created; do not use a standalone “Task Template” section
9	Checklist	Optional (only when process has multiple handoffs/steps)

Task Templates

When to Include

Include task templates inline where handoffs occur (not in a separate section). Place each template directly under the step that creates the task so the tool is there when the reader needs it.

Task title and description: Use actionable, self-explanatory text. Do not reference document step numbers (e.g. “Step 3”) in the title or description—the assignee cannot see which doc or process the step refers to. Example: use “Qualify lead: [Lead ID or short identifier]” not “Step 3: Qualify lead”.

Format

Use a table format:

|             | Task 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

Department vs project

Two separate fields, easy to confuse:

Field	Means
`dept`	Which Kiluth department owns the work — HR, Creative, Technology, Legal, Finance, Account Management, Marketing, Delivery, Operations
`project`	Which client project it belongs to, as a `PROJ-XXXX` id (e.g. `PROJ-0031`)

A task always has a department. It has a project unless it is standalone or Kiluth-native. Billable hours and expenses roll up by project, never by dept.

Cross-References & Links

Link Format & Graph View

Kiluth docs use Quartz’s graph view for navigation. Link format affects how nodes appear in the graph:

Link type	Trailing slash	Example
Parent / index (structural)	Yes	`[Technology](technology/)`, `[Completed](plans/completed/)`
Cross-reference (doc-to-doc)	No	`[Lead Qualification Guideline](account-management/lead-qualification-guideline)`

Use trailing slash for links to index/parent pages (department, plan status). Use no trailing slash for links to specific documents.

Internal Document References

When referencing other Kiluth docs, use markdown links with department/doc-name (no trailing slash):

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

Department Link (Structural)

For the Department block at the top of each document, link to the parent department index with a trailing slash (for graph navigation):

[Technology](technology/)

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 (link with trailing slash)
4	☐ Summary section present (after Department, before ToC)
5	☐ Table of Contents present and complete
6	☐ All lists converted to tables
7	☐ Outcome blocks use 1-column table format
8	☐ Decision points use 2-column table format
9	☐ Operating Model section uses standard 3-bullet text (if applicable)
10	☐ Kiluth Tasks templates use `<br>` for line breaks
11	☐ Section separators (`---`) between major sections
12	☐ Lists of 4+ items, checklists and process sequences are tables; bullets only for short asides (≤3 items) or lists nested inside another component
13	☐ Cross-references use markdown links (`[text](department/doc-name)`)
14	☐ No links to plans/ (planning docs are internal/confidential)
15	☐ No infrastructure or vendor platforms named (cloud, CDN, DNS, deploy tooling) — company-wide tools only; platform steps live in a runbook
16	☐ No prices or amounts — state what is charged for and when, not how much
17	☐ American spelling throughout (system terms like ERPNext’s `Cancelled` keep their own spelling)

Notes

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