Reference Document #

Ada satu jenis diskusi yang paling menguras energi tim engineering: bukan diskusi teknis yang sulit, melainkan diskusi tentang definisi — “apa yang kamu maksud dengan ‘high priority’?”, “ini bug severity apa?”, “kenapa formatnya beda dengan yang lain?”. Diskusi ini berulang, tidak ada habisnya, dan seringkali berakhir tanpa resolusi yang jelas karena setiap orang menggunakan standar masing-masing. Reference document adalah solusinya: dokumen acuan resmi yang mendefinisikan standar, terminologi, dan klasifikasi yang digunakan konsisten oleh seluruh tim. Bukan panduan proses, bukan design doc — melainkan kamus bersama yang menjawab pertanyaan “ketika kita bilang X, maksudnya apa?” Artikel ini membahas apa yang membuat reference document penting, contoh-contoh konkret yang umum dibutuhkan tim engineering, cara menyusunnya dengan efektif, dan anti-pattern yang membuat reference document menjadi dokumen mati.

Apa Itu Reference Document? #

Reference document adalah dokumen acuan resmi yang mendefinisikan standar, terminologi, aturan, dan klasifikasi yang digunakan secara konsisten oleh tim. Sifatnya normatif — ia tidak menjelaskan pendapat atau opsi, melainkan menetapkan standar yang berlaku.

Ciri khas yang membedakan reference document dari dokumen lain:

Reference Document vs Dokumen Lain:

Design Doc / RFC:
  → Menjelaskan keputusan teknis untuk perubahan spesifik
  → Dibuat per perubahan, bersifat sementara
  → Menjawab: "Bagaimana kita akan membangun X?"

Release Document:
  → Merangkum apa yang berubah di satu sprint
  → Dibuat per sprint, bersifat historis
  → Menjawab: "Apa yang berubah di sprint ini?"

Reference Document:
  → Mendefinisikan standar yang berlaku lintas sprint dan tim
  → Dibuat sekali, diperbarui saat standar berubah
  → Menjawab: "Ketika kita bilang X, maksudnya apa?"

Reference document menjawab pertanyaan-pertanyaan yang seharusnya tidak perlu ditanyakan berulang kali:

“Ini bug-nya severity apa?”
“Priority P1 itu berarti harus selesai kapan?”
“Format nama kolom database pakai apa — snake_case atau camelCase?”
“Error code untuk user not found itu apa?”
“Gimana cara nulis judul test case yang benar?”

Tanpa reference document, jawaban atas pertanyaan-pertanyaan ini bergantung pada siapa yang ditanya dan di hari apa. Hasilnya tidak konsisten — dan inkonsistensi di level standar menghasilkan inkonsistensi di level kode, testing, dan komunikasi tim.

Mengapa Reference Document Penting #

Menyamakan Persepsi Lintas Role #

Tim engineering terdiri dari orang-orang dengan latar belakang berbeda. Engineer yang sebelumnya bekerja di startup dengan 5 orang punya definisi “critical bug” yang berbeda dengan engineer yang sebelumnya di enterprise dengan ratusan ribu pengguna. QA punya standar keparahan bug yang mungkin berbeda dengan PM. Tanpa reference document, setiap diskusi tentang prioritas atau klasifikasi dimulai dari nol.

Tanpa reference document — skenario yang umum terjadi:
  QA: "Ini bug critical, harus fix sekarang!"
  Engineer: "Kayaknya ini cuma medium deh, masih ada workaround-nya"
  PM: "Tapi user-nya ngeluh, berarti high kan?"
  Tech Lead: "Oke kita diskusi dulu..."
  [30 menit kemudian]
  → Keputusan berdasarkan siapa yang paling keras suaranya

Dengan reference document:
  QA: "Ini masuk Critical — feature utama tidak bisa digunakan tanpa workaround"
  [Semua cek ke reference document]
  → Sepakat dalam 2 menit berdasarkan definisi yang sama

Menghilangkan Diskusi yang Tidak Produktif #

Diskusi tentang klasifikasi dan definisi adalah diskusi yang paling mudah dihilangkan — karena jawabannya seharusnya sudah ada. Waktu yang dihemat dari diskusi-diskusi ini bisa diinvestasikan ke problem teknis yang lebih substansial.

Reference document mengubah pertanyaan “menurut kamu ini apa?” menjadi “sesuai standar kita, ini masuk kategori mana?” — yang jauh lebih mudah dijawab dan lebih mudah disepakati.

Mempercepat Onboarding #

Engineer baru butuh waktu lama untuk memahami standar tidak tertulis yang ada di tim. Mereka harus belajar dari trial-and-error, dari feedback code review, dari pertanyaan yang terasa canggung untuk ditanyakan. Reference document mengkompres proses itu.

Onboarding tanpa reference document:
  Minggu 1: Engineer baru menulis test case dengan format yang tidak konsisten
  Minggu 2: Feedback di code review: "Judul test case-nya kurang jelas"
  Minggu 3: Menulis lagi, salah lagi, format masih berbeda dengan yang lain
  → Butuh 1-2 bulan untuk internalisasi standar tim

Onboarding dengan reference document:
  Hari 1: Engineer baru membaca reference doc (30 menit)
  Hari 2: Menulis test case dengan format yang benar dari awal
  → Standar terinternalisasi dalam hitungan hari

Menjadi Safety Net saat Keputusan di Bawah Tekanan #

Saat incident terjadi, saat sprint deadline mendekat, saat ada tekanan untuk “just ship it” — standar paling mudah dilanggar adalah standar yang tidak terdokumentasi. Reference document menjadi pegangan yang bisa dirujuk bahkan saat situasi paling kacau sekalipun.

Jenis Reference Document yang Umum Dibutuhkan Tim Engineering #

Severity Bug Level Reference #

Ini adalah reference document yang paling dibutuhkan hampir setiap tim. Tanpa definisi severity yang jelas, setiap bug triage menjadi negosiasi.

SEVERITY LEVEL REFERENCE

┌──────────┬────────────────────────────────────┬──────────────────────────────┐
│ Severity │ Definisi                           │ Contoh                       │
├──────────┼────────────────────────────────────┼──────────────────────────────┤
│ Critical │ Sistem tidak bisa digunakan.       │ Login down untuk semua user  │
│          │ Tidak ada workaround.              │ Data loss terjadi            │
│          │ Berdampak ke semua atau mayoritas  │ Payment tidak bisa diproses  │
│          │ pengguna.                          │ (semua transaksi gagal)      │
├──────────┼────────────────────────────────────┼──────────────────────────────┤
│ High     │ Fitur utama rusak atau tidak       │ Checkout gagal untuk         │
│          │ berfungsi. Ada workaround tapi     │ sebagian user                │
│          │ tidak praktis atau menyulitkan     │ Export laporan menghasilkan  │
│          │ pengguna secara signifikan.        │ data yang salah              │
├──────────┼────────────────────────────────────┼──────────────────────────────┤
│ Medium   │ Fitur sekunder rusak. Ada          │ Filter produk tidak bekerja  │
│          │ workaround yang cukup praktis.     │ Notifikasi email terlambat   │
│          │ Tidak menghalangi flow utama.      │ 10–15 menit                  │
├──────────┼────────────────────────────────────┼──────────────────────────────┤
│ Low      │ Issue minor yang tidak             │ Typo di label UI             │
│          │ mengganggu flow. Estetika atau     │ Tooltip tidak muncul         │
│          │ edge case yang jarang terjadi.     │ Animasi sedikit patah        │
└──────────┴────────────────────────────────────┴──────────────────────────────┘

Aturan tambahan:
  □ Data corruption atau data loss → selalu Critical, tidak peduli jumlah user
  □ Security vulnerability → selalu minimal High
  □ Bug yang hanya terjadi di browser tertentu → turunkan satu level dari estimasi awal
  □ Bug di environment non-production → catat tapi tidak masuk severity production

Priority Level Reference #

Priority berbeda dengan severity. Severity mengukur dampak — priority mengukur urgensi pengerjaan berdasarkan konteks bisnis. Bug severity Critical bisa jadi Priority P2 jika terjadi di fitur yang sedang di-sunset minggu depan.

PRIORITY LEVEL REFERENCE

P0 — Darurat (harus dikerjakan sekarang)
  Definisi: Blokir operasi bisnis atau menyebabkan reputational damage
            yang sedang berlangsung. Engineer harus stop pekerjaan lain.
  Target fix: Dalam jam yang sama, atau maksimal hari ini
  Contoh: Production down, data breach aktif, payment gagal massal

P1 — Sangat Penting (target sprint ini)
  Definisi: Berdampak signifikan ke pengguna atau bisnis tapi tidak
            menghentikan operasi. Harus masuk sprint saat ini.
  Target fix: Sebelum sprint berakhir
  Contoh: Fitur yang dijanjikan ke client belum berfungsi,
          bug High yang mempengaruhi >10% user aktif

P2 — Penting (target 1-2 sprint ke depan)
  Definisi: Perlu dikerjakan dalam waktu dekat tapi bisa ditunda.
  Target fix: Dalam 2 sprint ke depan
  Contoh: Bug Medium yang ada workaround, improvement performa

P3 — Nice to Have (backlog)
  Definisi: Bermanfaat tapi tidak mendesak. Dikerjakan kalau ada kapasitas.
  Target fix: Tidak ada target spesifik
  Contoh: Peningkatan estetika minor, edge case yang sangat jarang

Catatan penting:
  ✗ Severity dan priority adalah dua dimensi berbeda — jangan disamakan
  ✓ Bug Critical bisa jadi P2 jika fitur-nya akan di-deprecated minggu depan
  ✓ Bug Low bisa jadi P1 jika ada di landing page utama yang dilihat investor

Test Scenario Title Writing Reference #

Judul test case yang buruk adalah sumber kebingungan yang terakumulasi. Ketika test gagal di CI, developer harus membuka test tersebut untuk memahami apa yang seharusnya terjadi — padahal seharusnya judulnya sudah cukup.

TEST SCENARIO TITLE WRITING REFERENCE

Format yang disepakati:
  WHEN [kondisi / aksi user] THEN [hasil yang diharapkan]

Aturan:
  ✓ Mulai dengan WHEN atau Given-When-Then (pilih salah satu, konsisten)
  ✓ Kondisi harus spesifik — siapa yang melakukan apa dalam keadaan apa
  ✓ Hasil harus terukur dan observable
  ✗ Hindari kata ambigu: "works", "correctly", "properly", "successfully"
  ✗ Hindari judul yang mendeskripsikan implementasi, bukan perilaku

Contoh:

  ✗ Buruk: "Test login"
     → Tidak jelas kondisi apa, tidak jelas hasil apa yang diharapkan

  ✗ Buruk: "Login berfungsi dengan benar"
     → "Berfungsi dengan benar" tidak bisa diverifikasi

  ✓ Baik: "WHEN user submits valid email and password THEN user is
            redirected to dashboard with their name displayed"
     → Kondisi jelas, hasil jelas, bisa langsung diverifikasi

  ✗ Buruk: "Test email validation"
     → Validasi yang mana? Kondisi apa?

  ✓ Baik: "WHEN user submits email without @ symbol THEN validation
            error 'Invalid email format' is shown below the field"
     → Edge case spesifik, pesan error spesifik, lokasi error spesifik

  ✓ Baik: "WHEN user with expired session tries to access /dashboard
            THEN user is redirected to /login with message 'Session expired'"
     → Kondisi session spesifik, flow redirect jelas

Error Classification Reference #

Klasifikasi error yang konsisten adalah fondasi logging, alerting, dan retry strategy yang tepat. Error yang salah diklasifikasikan menghasilkan alert yang salah dan retry yang tidak perlu.

ERROR CLASSIFICATION REFERENCE

┌────────────────┬──────────────────────────────────────┬──────────────────────┐
│ Tipe Error     │ Definisi                             │ Contoh               │
├────────────────┼──────────────────────────────────────┼──────────────────────┤
│ Client Error   │ Kesalahan disebabkan oleh input      │ Field wajib kosong   │
│                │ atau request dari pengguna/client.   │ Format email salah   │
│                │ Bukan bug — sistem berperilaku benar.│ ID tidak ditemukan   │
│                │ HTTP 4xx                             │                      │
├────────────────┼──────────────────────────────────────┼──────────────────────┤
│ Business Error │ Request valid secara teknis tapi     │ Saldo tidak cukup    │
│                │ melanggar aturan bisnis domain.      │ Kuota upload tercapai│
│                │ HTTP 422 atau 409                    │ Order sudah expired  │
├────────────────┼──────────────────────────────────────┼──────────────────────┤
│ System Error   │ Kegagalan di level infrastruktur     │ DB connection gagal  │
│                │ atau sistem internal yang tidak      │ Disk penuh           │
│                │ bisa dikontrol oleh user.            │ Memory OOM           │
│                │ HTTP 5xx                             │                      │
├────────────────┼──────────────────────────────────────┼──────────────────────┤
│ Transient Error│ Error sementara yang kemungkinan     │ Timeout ke third-    │
│                │ akan hilang jika di-retry.           │ party API            │
│                │ Biasanya subset dari System Error.   │ Network blip         │
│                │ HTTP 503, 504, atau 429              │ Rate limit sementara │
└────────────────┴──────────────────────────────────────┴──────────────────────┘

Implikasi per tipe:
  Client Error   → Log level DEBUG/INFO, TIDAK alert, TIDAK retry
  Business Error → Log level INFO, TIDAK alert, TIDAK retry
  System Error   → Log level ERROR, ALERT ke on-call, TIDAK retry otomatis
  Transient Error→ Log level WARN, retry dengan backoff, alert jika retry habis

API Response Standard Reference #

Kontrak response API yang tidak konsisten adalah sumber frustrasi terbesar bagi developer yang mengonsumsi API tersebut — baik frontend internal maupun partner eksternal.

API RESPONSE STANDARD REFERENCE

Format response sukses:
{
  "data": <payload>,      // selalu ada untuk response sukses
  "meta": {               // opsional, untuk data paginasi
    "page": 1,
    "per_page": 20,
    "total": 150
  }
}

Format response error:
{
  "error": {
    "code": "USER_NOT_FOUND",     // snake_case, uppercase, konstanta
    "message": "User tidak ditemukan",  // human-readable, boleh dilokalisasi
    "details": []                 // opsional, untuk validation errors
  }
}

Format validation error (HTTP 422):
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Input tidak valid",
    "details": [
      {
        "field": "email",
        "message": "Format email tidak valid"
      },
      {
        "field": "phone",
        "message": "Nomor telepon wajib diisi"
      }
    ]
  }
}

Aturan error code:
  ✓ Format: NOUN_VERB atau NOUN_ADJECTIVE (e.g., USER_NOT_FOUND, ORDER_EXPIRED)
  ✓ Huruf besar semua, underscore sebagai separator
  ✗ Jangan gunakan angka sebagai error code (e.g., ERR_001) — tidak readable
  ✗ Jangan gunakan pesan teknis sebagai code (e.g., NULL_POINTER_EXCEPTION)

HTTP Status Code Mapping:
  200 OK          → Request berhasil, ada data yang dikembalikan
  201 Created     → Resource baru berhasil dibuat
  204 No Content  → Request berhasil, tidak ada data yang dikembalikan
  400 Bad Request → Request malformed (JSON tidak valid, parameter missing)
  401 Unauthorized→ Tidak ada atau token tidak valid
  403 Forbidden   → Token valid tapi tidak punya akses ke resource ini
  404 Not Found   → Resource tidak ditemukan
  409 Conflict    → Konflik state (duplikat, versi tidak cocok)
  422 Unprocessable→ Validasi bisnis gagal
  429 Too Many Requests → Rate limit
  500 Internal Error→ System error yang tidak terduga

Naming Convention Reference #

Inkonsistensi naming adalah salah satu sumber cognitive load terbesar di codebase yang besar. Ketika developer harus menebak apakah variabel di-format sebagai userId atau user_id atau UserID, konsentrasinya terpecah dari masalah yang sebenarnya.

NAMING CONVENTION REFERENCE

DATABASE:
  Tabel     → snake_case, plural  (e.g., user_orders, product_categories)
  Kolom     → snake_case, singular (e.g., user_id, created_at, is_active)
  Index     → idx_{tabel}_{kolom} (e.g., idx_orders_user_id)
  FK        → {tabel_referensi}_id (e.g., user_id, product_id)
  Timestamps→ created_at, updated_at, deleted_at (bukan created_date, dll)

JSON API:
  Keys      → camelCase (e.g., userId, createdAt, isActive)
  Arrays    → plural (e.g., "users": [], "items": [])
  Boolean   → is_ atau has_ prefix (e.g., isActive, hasChildren)

GOLANG (contoh untuk Go backend):
  Package   → lowercase, no underscore (e.g., userservice, orderrepo)
  Struct    → PascalCase (e.g., UserOrder, ProductCategory)
  Function  → PascalCase untuk exported, camelCase untuk unexported
  Constant  → PascalCase atau ALL_CAPS untuk truly constant values
  File      → snake_case (e.g., user_service.go, order_repository.go)

ENVIRONMENT VARIABLES:
  Format    → SCREAMING_SNAKE_CASE (e.g., DATABASE_URL, JWT_SECRET_KEY)
  Prefix    → gunakan prefix per service (e.g., PAYMENT_SERVICE_URL,
              NOTIFICATION_EMAIL_FROM)

URL PATH (REST API):
  Resources → lowercase, plural, kebab-case (e.g., /user-orders, /product-items)
  ID        → /:id (e.g., /users/:id, /orders/:orderId)
  Actions   → gunakan noun bukan verb (e.g., /orders/:id/cancellation,
              bukan /orders/:id/cancel)

✗ Anti-pattern naming yang harus dihindari:
  - Mixed conventions dalam satu codebase (userId di satu tempat, user_id di tempat lain)
  - Abbreviasi yang tidak universal (usrId, prodCat, trnx)
  - Nama generik tanpa konteks (data, info, temp, obj, item)
  - Boolean tanpa is_/has_ prefix (active, enabled, status booleans)

Cara Menyusun Reference Document yang Efektif #

1. Mulai dari Masalah yang Paling Sering Muncul #

Jangan coba membuat semua reference document sekaligus di awal. Identifikasi diskusi mana yang paling sering berulang dan paling menyita waktu — di situlah reference document paling dibutuhkan.

Cara identifikasi kebutuhan reference document:
  □ Retrospective: diskusi berulang apa yang muncul tentang standar atau definisi?
  □ Code review: feedback apa yang terus diulang ("format-nya harusnya begini")?
  □ Bug triage: pertanyaan apa yang selalu muncul? ("ini severity apa?")
  □ Onboarding: pertanyaan apa yang selalu ditanyakan engineer baru?

Mulai dengan yang paling sering terjadi, bukan yang paling lengkap.

2. Format Tabel untuk Klasifikasi, Prosa untuk Penjelasan Konteks #

Reference document bukan esai. Untuk klasifikasi dan standar, format tabel jauh lebih efektif — bisa dibaca dalam hitungan detik dan mudah di-scan saat diskusi cepat. Gunakan prosa hanya untuk menjelaskan konteks atau aturan yang tidak bisa dimasukkan ke tabel.

// ✗ Reference document yang terlalu bertele-tele:
"Bug dengan tingkat keparahan Critical adalah bug yang menyebabkan
sistem tidak dapat berfungsi sama sekali. Hal ini berbeda dengan
bug High yang mana sistem masih dapat berfungsi namun dengan
beberapa keterbatasan yang signifikan. Adapun bug Medium..."

// ✓ Reference document yang efektif:
| Severity | Sistem masih bisa digunakan? | Workaround tersedia? |
|---|---|---|
| Critical | Tidak | Tidak |
| High     | Sebagian | Tidak praktis |
| Medium   | Ya | Ya, cukup mudah |
| Low      | Ya | Tidak diperlukan |

3. Selalu Sertakan Contoh Konkret #

Definisi abstrak seringkali masih bisa diinterpretasikan berbeda-beda. Contoh konkret menghilangkan ambiguitas.

// ✗ Definisi tanpa contoh (masih ambigu):
"High severity: fitur utama rusak tanpa workaround yang praktis"

// ✓ Definisi dengan contoh:
"High severity: fitur utama rusak tanpa workaround yang praktis
 Contoh yang termasuk High:
   - Checkout flow error untuk semua browser di production
   - Export laporan menghasilkan data yang salah
   - Notifikasi transaksi tidak terkirim sama sekali
 Contoh yang TIDAK termasuk High (masuk Medium):
   - Filter di halaman produk tidak bekerja (ada workaround: pencarian manual)
   - Sorting tabel tidak konsisten (fitur sekunder)"

4. Pisahkan Reference dari Proses #

Reference document mendefinisikan apa — bukan bagaimana. Mencampur keduanya membuat dokumen lebih sulit digunakan sebagai referensi cepat.

// ✗ Mencampur reference dengan proses:
"Bug Critical adalah bug yang menyebabkan sistem tidak bisa digunakan.
Ketika ada bug Critical, langkah pertama adalah menghubungi on-call engineer
lewat PagerDuty. Setelah itu, buat tiket baru di Jira dengan label 'critical'.
Kemudian..."
→ Ini adalah runbook, bukan reference document

// ✓ Pisahkan dengan jelas:
Reference Document: "Bug Severity Definition"
  → Hanya mendefinisikan apa itu Critical, High, Medium, Low

Proses terpisah: "Incident Response Procedure"
  → Mendefinisikan langkah-langkah saat menemukan bug Critical

5. Pastikan Ada Owner dan Tanggal Terakhir Update #

Reference document yang tidak dirawat adalah dokumen yang berbahaya — lebih baik tidak ada daripada ada tapi sudah tidak akurat.

# Severity Bug Level Reference

**Owner:** QA Lead
**Terakhir diupdate:** 2026-01-15
**Disetujui oleh:** Engineering Manager, QA Lead, Tech Lead

---

*Untuk mengusulkan perubahan pada dokumen ini, buat tiket di backlog
dengan label "reference-doc-update" dan tag owner dokumen.*

6. Review Berkala, Bukan Hanya saat Ada Masalah #

Reference document perlu di-review secara proaktif — setidaknya setiap kuartal, atau saat ada perubahan signifikan pada tim, teknologi, atau proses.

Trigger untuk review reference document:
  □ Tim bertambah besar (standar yang cukup untuk 5 orang mungkin tidak
    cukup untuk 15 orang)
  □ Stack teknologi berubah (naming convention untuk framework baru)
  □ Feedback berulang bahwa standar yang ada tidak praktis
  □ Onboarding engineer baru menghasilkan banyak pertanyaan tentang standar
  □ Retrospective mengidentifikasi diskusi berulang tentang klasifikasi

Simpan semua reference document di satu tempat yang mudah diakses — wiki internal, Notion, atau folder /docs di repository. Buat indeks atau halaman “Standards & References” yang merupakan pintu masuk ke semua reference document yang ada. Dokumen yang tersebar di berbagai tempat akan diabaikan karena orang tidak tahu di mana mencarinya.

Anti-Pattern Reference Document #

Reference Document yang Tidak Pernah Diperbarui #

Reference document yang sudah usang lebih berbahaya dari tidak ada reference document sama sekali. Ia memberikan jawaban yang salah dengan keyakinan penuh.

// ✗ Skenario reference document yang basi:
Agustus 2024: Tim membuat severity reference document
Januari 2025: Tim memutuskan bahwa "data inconsistency" selalu Critical,
              tapi keputusan ini tidak diupdate di dokumen
Maret 2025: Bug triage menggunakan dokumen lama
            → Engineer meng-classify data inconsistency sebagai High
            → Response terlambat karena tidak ada yang dipanggil on-call

// ✓ Solusi: Setiap keputusan yang mengubah standar harus diikuti
   update ke reference document, bukan hanya disampaikan lisan

Reference Document yang Terlalu Granular #

Reference document yang mencoba mendefinisikan setiap kemungkinan edge case justru menjadi tidak bisa digunakan — terlalu panjang untuk dibaca cepat, dan perlu waktu terlalu lama untuk dipelihara.

// ✗ Reference document yang over-engineered:
Severity Bug Reference: 47 halaman
  - Section 1: Definisi umum
  - Section 2: Klasifikasi untuk mobile apps
  - Section 3: Klasifikasi untuk web apps
  - Section 4: Klasifikasi untuk API
  - Section 5: Edge cases untuk fitur payment
  - Section 6: Edge cases untuk fitur notifikasi
  - [40+ halaman lagi]
→ Tidak ada yang membaca, tidak ada yang menggunakannya

// ✓ Reference document yang efektif:
Severity Bug Reference: 1 halaman
  - Tabel 4 level dengan definisi dan 2-3 contoh per level
  - 5 aturan tambahan untuk edge case yang paling umum
  - Catatan: "Untuk kasus edge case yang tidak tercakup di sini,
    diskusikan dengan QA Lead"
→ Bisa dibaca dalam 5 menit, digunakan setiap hari

Reference Document Hanya Dimiliki Satu Orang #

Ketika reference document hanya ada di kepala atau laptop satu orang, ia berhenti menjadi reference document dan kembali menjadi pengetahuan personal.

// ✗ Situasi yang umum terjadi:
"Tanya si A aja soal severity level, dia yang paling tahu"
→ Si A resign → tim kehilangan standar
→ Si A sedang cuti → diskusi bug triage jadi debat tanpa resolusi
→ Si A di meeting → engineer baru tidak bisa maju

// ✓ Reference document yang benar-benar menjadi referensi:
- Dokumen tersimpan di wiki yang bisa diakses semua orang
- Link mudah dibagikan lewat Slack
- Disebutkan secara eksplisit di onboarding checklist engineer baru
- Digunakan secara rutin di bug triage, code review, dan diskusi tim

Tidak Ada Mekanisme untuk Mengusulkan Perubahan #

Reference document yang tidak bisa diubah (atau tidak jelas cara mengubahnya) akan diabaikan ketika standar yang ada tidak lagi relevan. Tim akan membuat standar informal tersendiri yang tidak terdokumentasi.

// ✗ Reference document tanpa proses update yang jelas:
"Dokumen ini final dan tidak bisa diubah"
atau
"Dokumen ini tidak ada proses update-nya"

→ Standar di dokumen makin jauh dari praktik aktual tim
→ Tim menggunakan standar informal yang tidak konsisten

// ✓ Proses update yang jelas:
Di bagian atas setiap reference document:
"Untuk mengusulkan perubahan: buat tiket dengan label 'standards-update',
 tag [owner dokumen], dan jelaskan mengapa perubahan diperlukan.
 Perubahan disetujui oleh Engineering Manager dan Tech Lead."

Reference document yang tidak digunakan dalam diskusi sehari-hari bukan reference document — ia hanya arsip. Indikator bahwa reference document hidup dan digunakan: disebutkan di code review (“sesuai naming convention kita di sini: [link]”), digunakan di bug triage (“ini masuk High berdasarkan definisi kita: [link]”), dan diperbarui saat ada diskusi yang menghasilkan keputusan tentang standar.

Ekosistem Reference Document yang Sehat #

Tim yang matang biasanya memiliki sekumpulan reference document yang saling melengkapi. Berikut ekosistem minimal yang perlu ada:

REFERENCE DOCUMENTS YANG DIBUTUHKAN TIM ENGINEERING

Tier 1 — Sangat Dibutuhkan (buat ini dulu):
  □ Severity Bug Level Reference
  □ Priority Level Reference
  □ API Response & Error Code Standard
  □ Naming Convention Reference (per layer: DB, API, code)

Tier 2 — Penting (buat setelah Tier 1 stabil):
  □ Test Scenario Writing Reference
  □ Error Classification Reference
  □ Logging Standard Reference (apa yang harus di-log, level apa)
  □ Git Commit Message Convention

Tier 3 — Berguna untuk tim yang lebih besar:
  □ Code Review Checklist Reference
  □ On-call Escalation Matrix
  □ Performance Budget Reference (threshold latency, error rate)
  □ Data Classification Reference (PII, public, internal, confidential)

Checklist Reference Document #

SAAT MEMBUAT REFERENCE DOCUMENT BARU:
  □ Ada kebutuhan yang jelas — diskusi berulang atau inkonsistensi yang teridentifikasi
  □ Format tabel digunakan untuk klasifikasi, bukan paragraf panjang
  □ Contoh konkret disertakan untuk setiap kategori utama
  □ Contoh "yang termasuk" DAN "yang tidak termasuk" disertakan
  □ Owner terdefinisi dan sudah menyetujui dokumen
  □ Tanggal pembuatan dan versi dicantumkan
  □ Proses untuk mengusulkan perubahan dijelaskan

KUALITAS KONTEN:
  □ Bisa dibaca dan dipahami dalam < 10 menit
  □ Tidak ada kata ambigu tanpa contoh (correctly, properly, significant)
  □ Reference document vs proses sudah dipisahkan
  □ Tidak ada duplikasi dengan reference document lain yang sudah ada

ADOPSI DAN PENGGUNAAN:
  □ Disimpan di tempat yang mudah diakses (bukan di email atau chat)
  □ Link dibagikan di channel engineering dan di onboarding checklist
  □ Disebutkan secara eksplisit di code review atau bug triage saat relevan
  □ Tim tahu di mana menemukannya tanpa harus bertanya

PEMELIHARAAN:
  □ Jadwal review berkala ditetapkan (minimal per kuartal)
  □ Owner masih aktif di tim — jika owner resign, tugaskan owner baru
  □ Perubahan pada standar selalu diikuti update ke dokumen
  □ Versi lama diarsipkan dengan catatan mengapa berubah

Ringkasan #

Reference document adalah kamus bersama tim — ia mendefinisikan makna standar, terminologi, dan klasifikasi yang digunakan konsisten oleh semua orang, lintas role dan lintas sprint.
Bedakan dari dokumen lain — RFC menjelaskan keputusan teknis, release document merangkum perubahan sprint, reference document mendefinisikan standar yang berlaku lintas waktu.
Mulai dari yang paling sering muncul — identifikasi diskusi berulang dan inkonsistensi yang paling menyita waktu tim, buat reference document untuk masalah itu dulu.
Format tabel untuk klasifikasi, prosa hanya untuk konteks — reference document harus bisa di-scan dalam hitungan detik, bukan dibaca seperti esai.
Selalu sertakan contoh konkret — definisi abstrak masih bisa diinterpretasikan berbeda. Contoh “yang termasuk” dan “yang tidak termasuk” menghilangkan ambiguitas.
Pisahkan definisi dari proses — reference document menjawab “apa”, runbook dan prosedur menjawab “bagaimana”.
Setiap reference document butuh owner — tanpa owner yang bertanggung jawab memperbarui dokumen, ia akan menjadi usang dan berbahaya.
Reference document yang tidak digunakan bukan reference document — ia harus disebutkan di code review, bug triage, dan diskusi standar secara aktif untuk tetap relevan.
Reference document yang usang lebih berbahaya dari yang tidak ada — ia memberikan jawaban yang salah dengan otoritas resmi. Review berkala adalah kewajiban, bukan opsional.
Proses untuk mengusulkan perubahan harus jelas — standar yang tidak bisa diperbarui akan diabaikan dan tim akan membuat standar informal tersendiri yang tidak terdokumentasi.

← Sebelumnya: Release Document Berikutnya: Syncup →