Membangun Budaya Dokumentasi: Mengapa Insinyur Tidak Menulis Dokumen dan Cara Memperbaikinya

Developer menghabiskan antara 3-10 jam per minggu mencari informasi yang seharusnya terdokumentasi. Untuk tim rekayasa 100 orang, itu adalah 300-1.000 jam per minggu — setara dengan 8-25 insinyur penuh waktu yang tidak melakukan apa-apa selain mencari jawaban. Karyawan baru membutuhkan 2-3 bulan lebih lama untuk menjadi produktif ketika dokumentasi buruk. Saya peduli tentang dokumentasi dengan mendalam — arsitektur situs portofolio ini terdokumentasi, modul ERP yang saya bangun di Commsult memiliki runbook, dan file README saya adalah hal pertama yang saya perbarui ketika arsitektur berubah.

Mengapa Insinyur Tidak Menulis Dokumentasi

Masalah dengan dokumentasi internal bukan bahwa insinyur tidak tahu itu penting — mereka tahu. Ini adalah masalah struktural dan budaya dengan tiga akar penyebab: (1) Tidak ada alokasi waktu — dokumentasi tidak pernah ada dalam sprint, jadi dipotong pertama kali. (2) Tidak ada visibilitas — tidak ada yang memuji dokumen yang bagus, tetapi semua orang memperhatikan dokumen yang hilang ketika mereka terblokir. (3) Dokumentasi yang basi secara aktif berbahaya.

Docs-as-Code: Satu Aturan yang Mengubah Segalanya

Dokumentasi yang jauh dari kode menjadi basi dengan cepat. Perubahan yang paling efektif: wajibkan pembaruan dokumentasi sebagai bagian dari PR yang sama yang membuat perubahan kode. Jika Anda mengubah endpoint API, PR menyertakan README atau dokumen API yang diperbarui. Ini adalah prinsip docs-as-code — perlakukan dokumentasi seperti kode, dengan review dan kontrol versi yang sama.

Docs-as-Code: Documentation Lives With Code

  Repository Structure:
  ─────────────────────────────────────────────
  invoice-service/
  ├── README.md                 ← 4 essentials: what/run/config/deploy
  ├── docs/
  │   ├── adr/
  │   │   ├── 001-use-bullmq-not-rabbitmq.md
  │   │   ├── 002-postgresql-not-mongodb.md
  │   │   └── 003-nestjs-cqrs-approval-flow.md
  │   ├── api/
  │   │   └── openapi.yaml     ← Updated in same PR as API changes
  │   └── runbooks/
  │       ├── deployment.md
  │       ├── rollback.md
  │       └── incident-response.md
  ├── .env.example              ← All env vars documented
  └── src/

  PR Template Documentation Checkbox:
  ─────────────────────────────────────────────
  - [ ] README updated (if setup/config changed)
  - [ ] ADR created (if significant decision made)
  - [ ] OpenAPI spec updated (if API changed)
  - [ ] .env.example updated (if new env vars added)
  - [ ] Runbook updated (if operational procedure changed)

Filosofi README-First

Setiap repositori harus memiliki README yang menjawab empat pertanyaan: (1) Apa ini? (satu kalimat yang mendeskripsikan apa yang dilakukan layanan/komponen); (2) Bagaimana cara menjalankannya secara lokal? (perintah yang tepat, bukan 'instal dependensi dan mulai'); (3) Bagaimana cara dikonfigurasi? (variabel lingkungan, feature flag, dependensi eksternal); (4) Bagaimana cara di-deploy?

# Invoice Service

One sentence: handles invoice creation, PDF generation, and payment tracking for Commsult ERP.

## Running Locally

```bash
# Prerequisites: Node 20+, Docker, PostgreSQL
cp .env.example .env          # copy and fill required values
docker-compose up -d postgres redis
npm install
npm run db:migrate
npm run dev                   # starts on :3002
```

## Configuration

| Variable           | Required | Description                        |
|--------------------|----------|------------------------------------|
| DATABASE_URL       | Yes      | PostgreSQL connection string        |
| REDIS_URL          | Yes      | Redis for BullMQ queues             |
| SMTP_HOST          | Yes      | SMTP server for email sending       |
| GCS_BUCKET         | Yes      | Google Cloud Storage for PDFs       |
| JWT_SECRET         | Yes      | Shared secret with API Gateway      |

## Deployment

CI/CD via GitHub Actions → Cloud Run (production) / staging on push to `main`.
Manual: `npm run deploy:staging` or `npm run deploy:prod`
Rollback: See [docs/runbooks/rollback.md](./docs/runbooks/rollback.md)

# ADR Format (docs/adr/001-use-bullmq-not-rabbitmq.md)
---
title: Use BullMQ instead of RabbitMQ for job queues
date: 2025-03-15
status: accepted
---
## Context
Need background job processing for PDF generation and email sending.
## Decision
Use BullMQ (Redis-backed) rather than RabbitMQ.
## Consequences
Simpler setup (Redis already in stack), Node.js only limitation accepted.

Architecture Decision Records

Architecture Decision Records (ADR) mendokumentasikan alasan di balik keputusan teknis yang signifikan — bukan apa (itu ada dalam kode) tetapi konteks, opsi yang dipertimbangkan, dan alasan untuk pendekatan yang dipilih. Format: judul pendek, tanggal, status (diusulkan/diterima/ditinggalkan), konteks, keputusan, dan konsekuensi. Simpan ADR dalam direktori /docs/adr di repositori.

Menjadikan Dokumentasi Bagian dari Budaya

Perubahan budaya memerlukan perubahan struktural. Intervensi struktural yang berhasil: (1) Tambahkan review dokumentasi ke checklist PR Anda. (2) Jadikan 'memperbarui README' bagian onboarding yang terlihat untuk setiap anggota tim baru — mereka memperbaiki apa yang membingungkan selama onboarding mereka sendiri. (3) Rayakan PR dokumentasi. (4) Buat sprint 'utang dokumentasi' sekali per kuartal.

Mengukur Kualitas Dokumentasi

Setiap peningkatan satu poin dalam skor dokumentasi berkorelasi dengan penghematan 13 menit per developer per minggu. Ukur kualitas dokumentasi melalui indikator utama: Berapa lama waktu yang dibutuhkan developer baru untuk membuat commit pertama mereka? Berapa banyak pesan Slack per minggu yang dijawab 'itu ada di README'? Berapa banyak insiden produksi yang diperpanjang karena runbook hilang atau sudah tidak berlaku?

Stack Dokumentasi Saya

Untuk ERP di Commsult: setiap layanan memiliki README dengan empat bagian esensial; keputusan arsitektur terdokumentasi dalam /docs/adr; perubahan API memerlukan pembaruan Swagger/OpenAPI dalam PR yang sama; prosedur operasional hidup dalam runbook Notion bersama. Untuk proyek pribadi (termasuk portofolio ini): README.md di root menjawab pengaturan dan deployment; komentar kode menjelaskan mengapa (bukan apa); dan saya menulis posting blog untuk keputusan arsitektur yang tidak jelas.

Sumber & Bacaan Lebih Lanjut

• DX — Developer Documentation: How to Measure Impact and Drive Engineering Productivity — https://getdx.com/blog/developer-documentation/
• DX — Motivating Developers to Care About Documentation — https://getdx.com/blog/documentation-culture-engineering/
• Shopify Engineering — How Good Documentation Can Improve Productivity — https://shopify.engineering/good-documentation-productivity