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, Asana card templates, and cross-reference style. Ensures consistency, readability, and compatibility with the documentation system.
Table of Contents
| Section | |
|---|---|
| 1 | Summary |
| 2 | Purpose |
| 3 | File Location & Naming |
| 4 | Document Structure |
| 5 | Content Formatting Rules |
| 6 | Standard Sections |
| 7 | Asana Card 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
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 3Example (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 | 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. |
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 | Asana card templates (inline) | At each handoff step where a task is created; do not use a standalone “Asana Card Template” section |
| 9 | 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). 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:
| | 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 |
Projects field vs Job ID at Kiluth
At Kiluth we use Asana Projects as Boards (e.g. HR, Creative, Technology, Legal, Finance, Account Management, Marketing, Delivery, Operations, Projects). The Projects field on a card means which board and column the card lives in (e.g. Creative / In progress), not the client’s project name. For client project linkage (billable hours, expenses), use the Job ID custom field (Project ID / Job ID, e.g. PROJ-0026). So: board/department = Projects field; client project = Job ID field.
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 | ☐ Asana templates use <br> for line breaks |
| 11 | ☐ Section separators (---) between major sections |
| 12 | ☐ No bullet points or numbered lists in content |
| 13 | ☐ Cross-references use markdown links ([text](department/doc-name)) |
| 14 | ☐ No links to plans/ (planning docs are internal/confidential) |
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