Reference Document #

Tim engineering yang scalable bukan hanya unggul di arsitektur dan kode — mereka juga kuat di shared understanding. Ketika setiap anggota tim memiliki definisi yang berbeda tentang apa itu “bug critical”, apa itu “P1”, atau bagaimana cara menulis nama endpoint yang benar, maka setiap diskusi berpotensi membuang waktu untuk menyamakan pemahaman yang seharusnya sudah selesai. Reference document adalah jawaban atas masalah itu: dokumen acuan resmi yang mendefinisikan standar, terminologi, dan klasifikasi yang digunakan secara konsisten oleh seluruh tim — lintas role, lintas sprint, lintas waktu.

Apa Itu Reference Document? #

Reference document adalah dokumen normatif yang mendefinisikan apa arti sesuatu di dalam konteks tim. Ia bukan dokumentasi teknis yang menjelaskan cara kerja sistem, bukan process guide yang menjelaskan langkah-langkah kerja, dan bukan RFC yang membahas keputusan arsitektur. Reference document menjawab satu pertanyaan sederhana yang sering menjadi sumber konflik:

“Ketika kita menyebut X, sebenarnya maksudnya apa?”

Ciri utama reference document yang membedakannya dari jenis dokumen lain:

Reference document hidup di antara dokumen-dokumen lain sebagai fondasi yang memastikan semua dokumen tersebut menggunakan terminologi yang sama.

flowchart TD
    RD[Reference Document\nstandar & terminologi]
    RFC[RFC\nkeputusan arsitektur]
    PG[Process Guide\ncara kerja]
    REL[Release Document\napa yang berubah]
    
    RD -->|"mendefinisikan terminologi untuk"| RFC
    RD -->|"mendefinisikan standar untuk"| PG
    RD -->|"mendefinisikan klasifikasi untuk"| REL

Mengapa Reference Document Penting? #

Menghilangkan Diskusi yang Sama Berulang-ulang #

Tanpa reference document, pertanyaan yang sama muncul setiap kali ada kasus baru:

// Skenario tanpa reference document
Bug triage meeting:
  QA: "Ini saya kasih severity High karena user tidak bisa checkout"
  Developer: "Tapi ada workaround, harusnya Medium"
  PM: "Ini harus P0 karena revenue impacted"
  → 20 menit diskusi, belum ada keputusan
  → Keputusan akhirnya bergantung pada siapa yang paling vokal

// Skenario dengan reference document
Bug triage meeting:
  QA: "Checkout gagal, tidak ada workaround → Severity: High sesuai referensi"
  PM: "Revenue impact > 10% → Priority: P1 sesuai referensi"
  → 2 menit, semua setuju, lanjut ke agenda berikutnya

Mengurangi Cognitive Load Tim #

Setiap keputusan yang tidak perlu dibuat ulang adalah energi mental yang tersisa untuk pekerjaan yang lebih bermakna. Reference document mengubah keputusan yang berulang menjadi lookup sederhana.

Mempercepat Onboarding #

Engineer baru tidak perlu menanyakan hal-hal dasar yang seharusnya sudah terdokumentasi:

// Onboarding tanpa reference document
Engineer baru: "Kalau bikin endpoint baru, pakai snake_case atau camelCase?"
Senior: "Tergantung... cek saja di kode yang sudah ada"
Engineer baru: "Di service A pakai snake_case, di service B pakai camelCase"
Senior: "Oh iya, kita memang belum konsisten, ikuti yang mayoritas saja"
→ Standar tidak jelas, kode makin tidak konsisten

// Onboarding dengan reference document
Engineer baru: buka Naming Convention Reference
→ "URL path: kebab-case, JSON body: camelCase, DB column: snake_case"
→ Langsung bisa bekerja tanpa bergantung pada orang lain

Menjaga Kualitas Tanpa Menambah Kompleksitas Teknis #

Reference document adalah quality guardrail yang tidak butuh tooling atau automation — hanya kesepakatan yang terdokumentasi dan dipatuhi bersama.

Jenis-jenis Reference Document di Tim Engineering #

Severity Bug Level Reference #

Severity mendefinisikan dampak bug terhadap sistem dan pengguna — independen dari seberapa cepat ia harus diperbaiki.

// Cara menggunakan severity reference
Pertanyaan 1: Apakah ada workaround yang praktis?
  → Tidak ada → minimal High
  → Ada tapi tidak praktis → pertimbangkan High atau Medium

Pertanyaan 2: Berapa banyak user yang terdampak?
  → Semua atau mayoritas user → naik satu level
  → Sebagian kecil user → pertahankan atau turun satu level

Pertanyaan 3: Apakah ada risiko data loss atau corruption?
  → Ya → Critical, tidak peduli jumlah user yang terdampak

Severity adalah penilaian teknikal/fungsional, bukan penilaian bisnis. Bug dengan Severity Medium bisa saja menjadi Priority P0 jika konteks bisnis mengharuskannya — misalnya, bug yang muncul tepat saat kampanye besar sedang berjalan.

Priority Level Reference #

Priority mendefinisikan urutan pengerjaan berdasarkan konteks bisnis dan dampak — bukan hanya severity teknikal.

// Perbedaan severity dan priority dalam praktik
Bug: Tombol "Export Laporan" tidak berfungsi

Severity: High
  → Fitur utama untuk segment merchant premium tidak bisa dipakai
  → Tidak ada workaround selain minta data manual ke CS

Priority: P1 (bukan P0)
  → Tidak memblokir transaksi atau revenue langsung
  → Tapi dialami oleh 200+ merchant aktif setiap hari
  → Target: diselesaikan sprint ini

// Contoh yang lebih kompleks
Bug: Typo pada halaman About Us

Severity: Low (tidak ada dampak fungsional)
Priority: P3 (dikerjakan jika ada kapasitas)
→ Severity dan Priority selaras untuk kasus sederhana

Bug: Fitur filter advanced tidak berfungsi di mobile

Severity: Medium (ada workaround: pakai desktop)
Priority: P1 (40% traffic berasal dari mobile, kampanye mobile dimulai minggu ini)
→ Priority lebih tinggi dari Severity karena konteks bisnis

Naming Convention Reference #

Naming convention adalah salah satu reference document yang dampaknya paling terasa langsung di codebase. Ketidakkonsistenan naming bukan hanya masalah estetika — ia meningkatkan cognitive load setiap engineer yang membaca kode.

// URL Path — gunakan kebab-case
✓ GET /api/v1/order-items
✓ POST /api/v1/user-addresses
✗ GET /api/v1/orderItems
✗ GET /api/v1/order_items

// JSON Request/Response Body — gunakan camelCase
✓ { "orderId": "...", "paymentMethod": "..." }
✗ { "order_id": "...", "payment_method": "..." }

// Database Table — gunakan snake_case, plural
✓ orders, order_items, user_addresses
✗ Order, orderItem, UserAddress

// Database Column — gunakan snake_case
✓ created_at, updated_at, order_status
✗ createdAt, UpdatedAt, orderStatus

// Environment Variable — gunakan SCREAMING_SNAKE_CASE
✓ DATABASE_HOST, REDIS_PORT, JWT_SECRET_KEY
✗ databaseHost, redis_port

// Go / Service Function — gunakan PascalCase (exported) atau camelCase (unexported)
✓ func ProcessPayment()  // exported
✓ func validateInput()   // unexported
✗ func process_payment()

Test Scenario Title Reference #

Judul test scenario yang tidak konsisten membuat test suite sulit dimaintain dan sulit dipahami ketika ada yang gagal.

// Format yang direkomendasikan: GIVEN-WHEN-THEN atau WHEN-THEN
// WHEN <kondisi> THEN <hasil yang diharapkan>

// ✓ Judul yang baik — eksplisit dan bisa berdiri sendiri
"WHEN user submits valid email and password THEN user is redirected to dashboard"
"WHEN user submits expired token THEN system returns 401 Unauthorized"
"WHEN cart is empty THEN checkout button is disabled"
"GIVEN user has pending order WHEN payment webhook received THEN order status updated to paid"

// ✗ Judul yang buruk — ambigu, tidak informatif saat gagal
"Test login"          → login yang mana? kondisi apa? hasil apa?
"Login works"         → "works" tidak bisa diverifikasi
"Verify checkout"     → verify apa?
"Happy path"          → happy path dari flow mana?

// Aturan tambahan:
✓ Hindari kata: "correctly", "properly", "works", "should"
✓ Sertakan kondisi (input/state) yang spesifik
✓ Sertakan expected outcome yang terukur
✓ Gunakan bahasa yang bisa dipahami non-engineer (untuk test yang didemonstrasikan ke PO)

Error Classification Reference #

Klasifikasi error yang konsisten memungkinkan logging, alerting, dan retry strategy yang tepat sasaran.

flowchart TD
    E[Error] --> CE{Client Error\n4xx}
    E --> BE{Business Error}
    E --> SE{System Error\n5xx}
    E --> TE{Transient Error}

    CE --> CE1["400 Bad Request\nInput tidak valid"]
    CE --> CE2["401 Unauthorized\nToken tidak ada/expired"]
    CE --> CE3["403 Forbidden\nTidak punya akses"]
    CE --> CE4["404 Not Found\nResource tidak ada"]

    BE --> BE1["Validasi domain gagal\nmisal: stok habis"]
    BE --> BE2["State transition invalid\nmisal: order sudah dibayar"]

    SE --> SE1["500 Internal Server Error\nUnhandled exception"]
    SE --> SE2["503 Service Unavailable\nDB/dependency down"]

    TE --> TE1["Timeout\nBisa di-retry"]
    TE --> TE2["Rate limited\nRetry dengan backoff"]

API Response Structure Reference #

Mendefinisikan struktur response yang konsisten di seluruh service mencegah frontend harus menebak-nebak format dan memudahkan error handling yang seragam.

// ✓ Success Response
{
  "success": true,
  "data": {
    "order_id": "ORD-2026-001",
    "status": "paid"
  },
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

// ✓ Error Response
{
  "success": false,
  "error": {
    "code": "PAYMENT_INSUFFICIENT_BALANCE",
    "message": "Saldo tidak mencukupi untuk menyelesaikan transaksi",
    "details": {
      "required": 150000,
      "available": 75000
    }
  }
}

// ✗ Format yang tidak konsisten (anti-pattern)
// Service A:
{ "status": "error", "msg": "not found" }
// Service B:
{ "success": false, "error_message": "User not found", "code": 404 }
// Service C:
{ "data": null, "errors": ["Resource does not exist"] }

Best Practice Menyusun Reference Document #

Prioritaskan Contoh di Atas Definisi #

Reference document yang hanya berisi definisi abstrak tidak akan digunakan. Yang membuat dokumen berguna adalah contoh konkret yang langsung bisa di-map ke situasi nyata.

// ✗ Definisi tanpa contoh — tidak membantu saat harus membuat keputusan
"Critical: Bug yang menyebabkan sistem tidak dapat digunakan"

// ✓ Definisi dengan contoh konkret — langsung bisa diterapkan
"Critical: Bug yang menyebabkan fitur utama tidak dapat digunakan oleh
mayoritas user, tanpa workaround yang praktis.
Contoh: Login page error 500 untuk semua user, payment gateway tidak merespons"

Pisahkan Reference dari Process #

Reference document menjawab apa, process guide menjawab bagaimana. Mencampurkan keduanya membuat dokumen sulit dinavigasi:

// ✗ Mencampur reference dan process dalam satu dokumen
"Severity High adalah bug yang memblokir fitur utama.
Cara menangani bug Severity High:
1. Buka tiket di Jira
2. Assign ke developer on-call
3. Update status setiap 2 jam"

// ✓ Pisahkan menjadi dua dokumen
Severity Level Reference → mendefinisikan apa itu High, Critical, Medium, Low
Bug Handling Process → menjelaskan langkah-langkah penanganan per severity

Tetapkan Owner dan Jadwal Review #

Reference document tanpa owner akan menjadi basi — definisi yang sudah tidak relevan dengan kondisi tim saat ini tapi tidak ada yang berani mengubahnya.

// Header yang seharusnya ada di setiap reference document
---
Owner: [nama atau tim]
Terakhir Diperbarui: YYYY-MM-DD
Jadwal Review: Setiap kuartal atau saat ada perubahan signifikan
Berlaku Untuk: Seluruh tim engineering
---

Buat Mudah Dicari dan Diakses #

Reference document yang tersembunyi di folder yang tidak ada yang tahu sama saja tidak ada. Simpan di tempat yang mudah diakses, dengan judul yang eksplisit dan bisa dicari:

// ✓ Struktur folder yang baik
/docs
  /reference
    severity-bug-level.md
    priority-level.md
    naming-convention.md
    error-classification.md
    api-response-structure.md
    test-scenario-title-convention.md

// ✗ Struktur yang menyulitkan pencarian
/docs
  /general
    /standards
      /v2
        misc-standards-final-rev3.md   ← siapa yang akan menemukan ini?

Gunakan Aktif di Meeting dan Review #

Reference document yang hanya dibaca sekali saat onboarding bukan reference document yang efektif. Ia harus hidup — digunakan secara aktif saat bug triage, code review, dan sprint planning:

// Contoh penggunaan aktif dalam berbagai konteks
Bug Triage:
  "Ini Severity High karena tidak ada workaround — sesuai definisi di referensi kita"

Code Review:
  "URL ini harusnya pakai kebab-case, bukan camelCase — cek Naming Convention Reference"

Sprint Planning:
  "Story ini berdampak ke payment flow — kita perlu mendefinisikan error code baru,
  update dulu di Error Classification Reference sebelum implementasi"

Anti-Pattern Reference Document #

// ✗ Reference document yang terlalu panjang dan akademis
Halaman 1-5: sejarah dan teori severity classification
Halaman 6-10: perbandingan dengan industri lain
Halaman 11: tabel severity yang sebenarnya dibutuhkan
→ Tidak ada yang membacanya — terlalu melelahkan untuk informasi yang simple
// ✓ Langsung ke tabel dan contoh, teori cukup 2-3 kalimat pengantar

// ✗ Reference document tanpa contoh konkret
"Critical: Bug yang sangat parah dan berdampak luas"
→ "Sangat parah" dan "berdampak luas" masih subjektif
// ✓ Sertakan contoh nyata dari sistem yang sedang dibangun

// ✗ Reference document yang tidak pernah diperbarui
Dokumen terakhir diperbarui 2 tahun lalu
Stack teknologi sudah berubah, tapi naming convention masih mengacu ke stack lama
→ Tim tidak percaya pada dokumen yang sudah usang
// ✓ Tetapkan owner dan jadwal review yang jelas

// ✗ Multiple reference document yang saling bertentangan
Bug Severity Reference di Confluence: 4 level (Critical, High, Medium, Low)
QA Handbook di Notion: 5 level (Critical, Major, Minor, Trivial, Enhancement)
→ Tidak ada "sumber kebenaran tunggal"
// ✓ Satu reference untuk satu topik, simpan di satu tempat

// ✗ Reference document yang hanya diketahui sebagian tim
"Oh itu ada di folder lama, saya lupa di mana"
→ Kalau tidak semua orang tahu di mana dokumennya, dokumen itu tidak ada secara efektif
// ✓ Link ke semua reference document disertakan di onboarding material dan README

Checklist Reference Document yang Sehat #

KONTEN:
  □ Fokus pada satu topik — tidak mencampur reference dan process
  □ Setiap definisi disertai minimal satu contoh konkret
  □ Menggunakan terminologi yang konsisten dengan codebase dan komunikasi sehari-hari
  □ Tidak ada definisi yang ambigu atau bisa diinterpretasikan berbeda-beda

PENGELOLAAN:
  □ Ada owner yang bertanggung jawab menjaga dokumen tetap akurat
  □ Ada tanggal "terakhir diperbarui" yang terlihat jelas
  □ Ada jadwal review berkala (minimal sekali per kuartal)
  □ Perubahan pada dokumen dikomunikasikan ke seluruh tim yang terdampak

AKSESIBILITAS:
  □ Disimpan di tempat yang mudah ditemukan dan mudah dicari
  □ Judul dokumen eksplisit dan deskriptif
  □ Link ke dokumen ini disertakan di onboarding material tim
  □ Bisa dibuka dan dibaca dalam < 5 menit untuk kasus penggunaan yang umum

PENGGUNAAN:
  □ Tim aktif merujuk dokumen ini saat bug triage, code review, dan diskusi teknis
  □ Jika ada yang bertanya tentang definisi tertentu, jawabannya selalu "cek referensi"
  □ Jika ada kasus yang tidak ter-cover oleh dokumen, dokumen langsung diperbarui

Ringkasan #

• Reference document mendefinisikan “apa arti X” — bukan cara melakukannya — pisahkan dari process guide dan RFC.
• Contoh konkret lebih berharga dari definisi abstrak — “Critical: login down untuk semua user” lebih berguna dari “Critical: dampak luas terhadap sistem”.
• Severity dan priority adalah dua dimensi yang berbeda — severity mengukur dampak teknikal/fungsional, priority mengukur urutan pengerjaan berdasarkan konteks bisnis.
• Naming convention yang konsisten mengurangi cognitive load — URL, JSON, DB column, dan env variable masing-masing punya konvensi yang harus didokumentasikan.
• Test scenario title harus bisa berdiri sendiri — format WHEN-THEN memastikan siapapun yang melihat test yang gagal langsung memahami konteksnya.
• Reference document harus hidup, bukan pajangan — gunakan secara aktif di bug triage, code review, dan onboarding.
• Satu topik, satu dokumen, satu sumber kebenaran — reference yang terfragmentasi di berbagai tempat sama buruknya dengan tidak ada reference sama sekali.
• Tetapkan owner dan jadwal review — dokumen tanpa owner akan menjadi basi dan tidak lagi dipercaya tim.

← Sebelumnya: Release Document   Berikutnya: Syncup →