Dokumentasi repo yang berantakan itu bukan cuma bikin developer baru nyasar. Di era AI coding agent, itu juga bikin agent lu salah baca niat project.
Artikel ini membahas Diátaxis, framework dokumentasi teknis yang membagi docs jadi empat jenis: tutorial, how-to guide, reference, dan explanation. Intinya sederhana: dokumentasi yang bagus bukan sekadar panjang, tapi jelas menjawab kebutuhan pembaca. Buat developer, tech lead, dan builder yang mulai pakai AI coding agent, struktur dokumentasi seperti ini bisa jadi interface kerja yang lebih rapi buat manusia dan agent.
Apa itu Diátaxis?
Diátaxis adalah pendekatan sistematis untuk menulis dan menyusun dokumentasi teknis. Framework ini bilang bahwa user dokumentasi biasanya datang dengan kebutuhan yang berbeda. Ada yang baru belajar dari nol. Ada yang cuma mau menyelesaikan satu masalah. Ada yang butuh detail API. Ada juga yang butuh memahami alasan desain di balik sistem.
Masalahnya, banyak repo mencampur semua kebutuhan itu ke satu file README super panjang atau wiki yang tumbuh liar. Hasilnya kelihatan lengkap, tapi pas dipakai terasa melelahkan. Lu mau cari cara setup lokal, ketemu sejarah arsitektur. Lu mau cari opsi config, ketemu tutorial onboarding. Lu mau tahu alasan tradeoff teknis, malah dilempar ke daftar command.
Diátaxis memecah dokumentasi ke empat bentuk:
- Tutorial: ngajarin user belajar lewat langkah terarah.
- How-to guide: membantu user menyelesaikan problem spesifik.
- Reference: menjelaskan detail teknis secara rapi dan ringkas.
- Explanation: memberi konteks, alasan, dan mental model.
Empat jenis ini kelihatan sederhana, tapi efeknya besar. Gua sering lihat dokumentasi gagal bukan karena kurang niat, tapi karena jenis dokumennya dicampur sampai pembaca harus nebak sendiri: “ini buat belajar, buat eksekusi, buat lookup, atau buat memahami alasan?”
Kenapa dokumentasi panjang sering tetap susah dipakai?
Dokumentasi panjang sering memberi rasa aman palsu. Tim merasa “semua sudah ditulis”, padahal struktur informasinya belum membantu orang mengambil tindakan. Ini mirip codebase: banyak baris kode bukan berarti desainnya bagus.
Contoh paling umum: README project internal yang isinya campuran begini:
- cara install dependency,
- cerita kenapa service ini dibuat,
- daftar environment variable,
- troubleshooting database,
- aturan deployment,
- dan catatan incident tahun lalu.
Semua poin itu mungkin penting. Tapi kalau ditaruh tanpa pemisahan niat, orang yang lagi panik karena deploy gagal harus membaca dokumen seperti novel detektif. Di situ dokumentasi berubah dari alat bantu jadi friction.
Buat AI coding agent, masalah ini makin terasa. Agent bisa membaca banyak file, tapi kalau dokumen lu nggak punya struktur niat yang jelas, agent tetap bisa salah prioritas. Dia bisa menganggap explanation sebagai instruksi wajib, atau menganggap contoh tutorial sebagai pattern produksi. Context window besar nggak otomatis menyelesaikan ambiguity.
Dokumentasi repo sekarang juga interface buat AI agent
Beberapa tahun lalu, dokumentasi repo terutama dibaca manusia. Sekarang, makin banyak workflow yang melibatkan AI coding agent: Copilot, Claude Code, Codex, Cursor, atau agent internal lain. Bahkan GitHub Copilot Code Review sudah mendukung file AGENTS.md sebagai konteks repository-level untuk membantu review.
Artinya, docs bukan cuma arsip pengetahuan. Docs mulai jadi interface operasional. Kalau interface-nya rapi, manusia dan agent punya peluang lebih besar untuk bergerak di arah yang sama. Kalau interface-nya kabur, agent bisa terlihat produktif sambil menghasilkan perubahan yang melenceng.
Menurut gua, ini titik penting: AI agent bukan cuma butuh prompt. Dia butuh peta kerja. Dan peta kerja yang bagus biasanya bukan satu dokumen raksasa, tapi kumpulan dokumen kecil yang jelas fungsinya.
Empat jenis docs yang sebaiknya lu pisahkan
1. Tutorial: buat orang yang lagi belajar
Di Diátaxis, tutorial itu learning-oriented. Tujuannya bukan menyelesaikan semua kasus nyata, tapi membimbing user belajar lewat aktivitas yang meaningful. Buat repo, ini bisa berupa “membuat fitur kecil pertama”, “menjalankan local development dari nol”, atau “membuat integration test pertama”.
Tutorial yang bagus harus ramah buat pemula di project itu. Jangan langsung penuh edge case. Jangan membuat user memilih lima jalur setup sebelum paham sistemnya. Pegang tangan dulu, baru jelaskan variasi belakangan.
2. How-to guide: buat problem spesifik
How-to guide itu goal-oriented. User datang karena ingin menyelesaikan satu hal: reset database lokal, rotate API key, deploy worker baru, rollback release, atau menambah endpoint.
Format how-to sebaiknya langsung ke langkah. Kalau ada risiko, tulis jelas. Kalau ada precondition, sebutkan di awal. Jangan menyembunyikan command penting di tengah paragraf panjang.
Contoh judul yang jelas:
- “Cara menjalankan migration di staging”
- “Cara rollback release Ghost CMS”
- “Cara menambah environment variable baru”
Judul seperti ini lebih berguna daripada “Deployment Notes” yang isinya campur aduk.
3. Reference: buat lookup detail
Reference itu information-oriented. Dia harus rapi, lengkap, dan mudah dicari. Contohnya daftar environment variable, endpoint API, struktur event, config, CLI flags, atau contract payload.
Reference nggak perlu terlalu banyak cerita. Kalau user lagi lookup nama field atau default value, dia nggak butuh motivasi panjang. Dia butuh jawaban yang presisi.
Di sinilah banyak dokumentasi repo kebalik. Bagian reference dibuat seperti artikel edukasi, sementara bagian tutorial terlalu kering seperti tabel config. Akhirnya dua-duanya nggak enak dipakai.
4. Explanation: buat memahami alasan
Explanation itu understanding-oriented. Ini tempat buat membahas kenapa sistem didesain begitu, tradeoff apa yang diambil, kenapa tidak pakai pendekatan lain, dan konteks sejarah keputusan.
Bagian ini penting banget untuk AI-era software development. Karena agent bisa meniru pola kode, tapi dia tidak otomatis tahu alasan di balik pola itu. Kalau alasan desain cuma hidup di kepala satu orang, agent dan developer baru sama-sama rawan salah interpretasi.
Contoh explanation yang berguna:
- “Kenapa service ini pakai SQLite, bukan Postgres”
- “Kenapa worker ini idempotent”
- “Kenapa fitur export tidak jalan realtime”
Dokumen seperti ini membantu orang mempertahankan desain yang benar, bukan cuma menjalankan command yang benar.
Checklist praktis buat merapikan docs repo minggu ini
Lu nggak perlu langsung migrasi semua dokumentasi ke sistem besar. Mulai dari audit kecil. Buka README atau wiki repo lu, lalu tanya:
- Apakah onboarding pemula punya jalur tutorial yang jelas?
- Apakah problem operasional punya how-to guide yang langsung bisa dieksekusi?
- Apakah detail API/config dipisahkan sebagai reference?
- Apakah alasan desain penting ditulis sebagai explanation?
- Apakah AI agent bisa membedakan instruksi wajib, contoh, dan konteks?
- Apakah dokumen lama punya owner atau tanggal terakhir divalidasi?
Kalau mau format minimal, gua suka struktur seperti ini:
/docs
/tutorials
local-development.md
/how-to
rotate-api-key.md
rollback-release.md
/reference
env-vars.md
api-events.md
/explanation
architecture-decisions.md
AGENTS.md
README.mdREADME tetap penting, tapi tugasnya sebagai pintu masuk. Jangan paksa README menjadi seluruh perpustakaan.
Bagaimana ini nyambung ke personal knowledge management?
Buat gua, Diátaxis bukan cuma soal dokumentasi produk. Ini juga relevan buat Obsidian, Hermes Agent, dan sistem catatan pribadi. Banyak second brain gagal karena semua catatan diperlakukan sama: ide mentah, runbook, keputusan, referensi, dan jurnal kerja masuk satu tumpukan.
Padahal kebutuhan membaca catatan juga beda. Saat debugging, lu butuh how-to. Saat belajar tool baru, lu butuh tutorial. Saat setup automation, lu butuh reference. Saat mengevaluasi keputusan, lu butuh explanation.
Kalau catatan lu makin sering dibaca AI agent, struktur ini makin penting. Agent bisa lebih berguna kalau catatan lu punya sinyal niat. Markdown itu boring, tapi justru karena boring dia enak dibaca mesin dan manusia.
Kesimpulan: docs bukan sisa kerja, docs adalah bagian dari sistem
Diátaxis mengingatkan hal yang sering kelewat: dokumentasi bukan satu aktivitas tunggal. Dokumentasi punya beberapa bentuk, karena user datang dengan kebutuhan yang berbeda. Tutorial mengajari. How-to membantu eksekusi. Reference memberi detail. Explanation memberi pemahaman.
Di era AI coding agent, pemisahan ini makin berharga. Repo lu bukan cuma dibaca tim manusia, tapi juga software yang bisa mengubah file, menulis PR, dan memberi review. Kalau docs lu kabur, agent lu ikut kabur. Kalau docs lu rapi, docs itu jadi operating layer kecil yang bikin kerja manusia dan AI lebih bisa dipercaya.
Takeaway paling praktis: jangan mulai dari “tulis dokumentasi lebih banyak”. Mulai dari “pisahkan jenis dokumentasi yang berbeda”. Itu langkah kecil, tapi efeknya bisa langsung terasa di onboarding, debugging, review PR, dan workflow AI agent.
FAQ singkat
Apakah Diátaxis cocok buat project kecil?
Cocok, asal jangan dibuat terlalu berat. Untuk project kecil, cukup pisahkan README, beberapa how-to penting, reference config, dan satu dokumen explanation untuk keputusan arsitektur utama.
Apakah AGENTS.md menggantikan dokumentasi biasa?
Nggak. AGENTS.md lebih cocok sebagai instruksi operasional buat AI agent. Dokumentasi biasa tetap dibutuhkan untuk onboarding manusia, referensi teknis, dan konteks desain.
Mana yang harus dibuat dulu?
Mulai dari how-to yang paling sering ditanyakan tim. Kalau pertanyaan yang sama muncul tiga kali, itu kandidat kuat jadi dokumen.
