Reference Document #

Dalam tim engineering yang sehat dan scalable, reference document memegang peran yang sangat krusial. Ia sering kali tidak dianggap sebagai “core deliverable”, namun justru menjadi fondasi yang menentukan konsistensi keputusan, kecepatan eksekusi, dan kualitas kolaborasi.

Tanpa reference document, tim akan bergantung pada interpretasi personal, asumsi, dan ingatan individu—yang pada akhirnya memicu debat berulang, inkonsistensi, dan technical debt non-teknis.

Artikel ini membahas apa itu reference document, tujuannya, nilai pentingnya, contoh-contoh konkret yang umum digunakan di tim engineering, serta best practice dalam menyusunnya.

Apa Itu Reference Document? #

Reference document adalah dokumen acuan resmi yang mendefinisikan standar, terminologi, aturan, dan klasifikasi yang digunakan secara konsisten oleh tim engineering.

Ciri utama reference document:

• Bersifat normatif (menentukan standar, bukan opini)
• Digunakan lintas role (engineer, QA, PM, support)
• Menjadi rujukan saat terjadi perbedaan interpretasi
• Relatif stabil (tidak sering berubah seperti task atau ticket)

Reference document berbeda dengan:

• Design doc → fokus ke solusi teknis spesifik
• PRD → fokus ke kebutuhan produk
• Runbook → fokus ke operasional

Reference document menjawab pertanyaan:

“Ketika kita bilang X, sebenarnya maksudnya apa?”

Tujuan Reference Document #

Menyamakan Persepsi #

Setiap orang membawa latar belakang dan pengalaman berbeda. Reference document menyamakan definisi agar:

• “High priority” berarti hal yang sama untuk semua
• “Critical bug” tidak diperdebatkan tiap incident

Mengurangi Diskusi Berulang #

Tanpa reference, diskusi akan terus berulang:

• “Ini severity apa?”
• “Test case ini sudah valid belum?”

Dengan reference:

“Kita cek ke dokumen referensi saja.”

Mempercepat Pengambilan Keputusan #

Keputusan tidak perlu dibuat dari nol. Tim cukup memetakan kasus ke kategori yang sudah didefinisikan.

Onboarding Lebih Cepat #

Engineer baru bisa:

• Memahami standar tim tanpa harus bertanya terus
• Menghindari trial-and-error yang mahal

Menjaga Konsistensi Kualitas #

Reference document adalah bentuk quality guardrail non-teknis.

Contoh Reference Document di Tim Engineering #

Severity Bug Level Reference #

Digunakan untuk mengklasifikasikan dampak bug terhadap sistem dan user.

Contoh:

Manfaat:

• QA dan engineer berbicara dengan bahasa yang sama
• Incident response lebih terukur

Priority Level Reference #

Berbeda dengan severity. Priority berbicara soal urutan pengerjaan, bukan dampak.

Contoh:

Catatan penting:

• Bug severity High tidak selalu priority P0
• Priority mempertimbangkan konteks bisnis

Test Scenario Title Writing Reference #

Sering dianggap sepele, tapi sangat penting untuk keterbacaan dan maintainability test.

Contoh aturan:

• Gunakan pola: WHEN <kondisi> THEN <hasil yang diharapkan>
• Hindari kata ambigu seperti “works”, “correctly”

Contoh:

• ❌ “Test login”
• ✅ “WHEN user submits valid email and password THEN user is redirected to dashboard”

Manfaat:

• Test mudah dipahami tanpa baca detail
• Fail test langsung memberi konteks

Error Classification Reference #

Digunakan untuk membedakan jenis error di sistem.

Contoh:

• Client Error (4xx): kesalahan input user
• Business Error: validasi domain
• System Error: DB down, timeout
• Transient Error: error sementara yang bisa retry

Manfaat:

• Logging dan alerting lebih akurat
• Retry strategy lebih tepat

API Response & Error Code Reference #

Menentukan:

• Struktur response
• Kode error yang diperbolehkan
• Mapping error ke HTTP status

Contoh:

{
  "error_code": "USER_NOT_FOUND",
  "message": "User does not exist"
}

Manfaat:

• Frontend tidak menebak-nebak
• Backward compatibility lebih terjaga

Naming Convention Reference #

Mencakup:

• Variable
• Table
• Column
• Endpoint

Contoh:

• snake_case untuk database
• camelCase untuk JSON

Manfaat:

• Codebase konsisten
• Mengurangi cognitive load

Best Practice Menyusun Reference Document #

Jangan Terlalu Akademis #

Reference document harus:

• Singkat
• Jelas
• Bisa dipakai saat diskusi cepat

Lebih baik:

“Jika A terjadi, maka kategorinya B”

Daripada definisi panjang tanpa contoh.

Fokus pada Keputusan, Bukan Penjelasan Panjang #

Reference document tidak perlu menjelaskan semua teori, cukup:

• Batasan
• Klasifikasi
• Contoh

Pisahkan Reference dari Process #

• Reference → apa arti sesuatu
• Process → bagaimana cara melakukannya

Jangan mencampur keduanya.

Mudah Diakses dan Mudah Dicari #

Simpan di:

• Wiki internal
• Notion
• Repository docs

Pastikan:

• Link mudah dibagikan
• Judul eksplisit

Versioned dan Ada Owner #

Setiap reference document harus punya:

• Owner (PIC)
• Riwayat perubahan

Tanpa owner, dokumen akan basi.

Digunakan Saat Review dan Diskusi #

Reference document harus hidup, bukan pajangan.

Contoh penggunaan:

• Code review
• Bug triage
• Incident postmortem

Penutup #

Reference document adalah alat scaling tim, bukan sekadar dokumentasi.

Ia mengurangi friksi manusia, mempercepat keputusan, dan menjaga kualitas tanpa harus menambah kompleksitas teknis.

Tim engineering yang matang bukan hanya unggul di arsitektur dan code, tetapi juga kuat di shared understanding—dan reference document adalah salah satu pilar utamanya.