Dokumentasi Proyek

Mengapa Dokumentasi Penting

• Tim baru bisa memahami sistem tanpa harus bertanya ke semua orang
• Keputusan arsitektur tidak hilang ketika anggota tim keluar
• Memudahkan debugging dan troubleshooting
• Membantu onboarding lebih cepat

Jenis Dokumentasi

Requirements Document

• Mendeskripsikan apa yang harus dilakukan sistem
• Mencakup kebutuhan fungsional dan non-fungsional
• Dasar untuk testing dan acceptance criteria

Technical Design Document (TDD)

• Menjelaskan bagaimana sistem dibangun secara teknis
• Mencakup arsitektur, database schema, dan alur data
• Ditulis sebelum implementasi dimulai

API Documentation

• Mendokumentasikan endpoint, request, dan response
• Memudahkan developer lain menggunakan API
• Tools: Swagger/OpenAPI, Postman Collection

README

• Titik masuk pertama untuk developer baru
• Berisi cara setup, menjalankan, dan berkontribusi ke proyek
• Harus selalu diperbarui mengikuti perubahan

Architecture Decision Record (ADR)

• Mendokumentasikan keputusan arsitektur dan alasannya
• Format: konteks, keputusan, konsekuensi
• Membantu tim memahami mengapa sistem dibangun seperti ini

Runbook / Playbook

• Panduan operasional untuk menjalankan dan memelihara sistem
• Berisi prosedur untuk deployment, rollback, dan incident response
• Penting untuk tim operasional dan on-call

Dokumentasi Kode

Komentar yang Baik

• Jelaskan mengapa, bukan apa yang dilakukan kode
• Hindari komentar yang hanya mengulang kode
• Tambahkan komentar untuk logika yang kompleks atau tidak intuitif

Docstring dan Type Hints

• Dokumentasikan fungsi publik dengan docstring
• Gunakan type hints untuk memperjelas tipe input dan output
• Membantu IDE memberikan autocomplete yang akurat

Pengelolaan Dokumentasi

Simpan Bersama Kode

• Dokumentasi disimpan di repository yang sama dengan kode
• Diperbarui bersama perubahan kode dalam satu commit
• Menghindari dokumentasi yang ketinggalan jaman

Documentation as Code

• Tulis dokumentasi dalam format teks (Markdown, AsciiDoc)
• Bisa di-review melalui pull request seperti kode
• Bisa digenerate otomatis menjadi website

Single Source of Truth

• Hindari duplikasi dokumentasi di banyak tempat
• Satu sumber utama, referensikan dari tempat lain
• Menghindari inkonsistensi antar dokumen

Prinsip Dokumentasi yang Baik

Jelas dan Ringkas

• Gunakan bahasa yang mudah dipahami
• Hindari jargon yang tidak perlu
• Lebih pendek tapi jelas lebih baik dari panjang tapi membingungkan

Selalu Diperbarui

• Dokumentasi yang salah lebih berbahaya dari tidak ada dokumentasi
• Jadikan update dokumentasi bagian dari Definition of Done
• Review dokumentasi secara berkala

Terstruktur dan Mudah Dicari

• Gunakan heading dan daftar isi
• Beri nama file dan bagian yang deskriptif
• Sediakan search jika dokumentasi sudah besar

Anti-Pattern

• Dokumentasi yang sudah kedaluwarsa dan tidak diperbaiki
• Mendokumentasikan hal yang sudah jelas dari kode
• Menulis dokumentasi hanya di kepala atau Slack
• Menyimpan dokumentasi di tempat yang tidak bisa diakses semua orang

Praktik Terbaik

• Jadikan dokumentasi bagian dari proses development, bukan afterthought
• Gunakan template untuk konsistensi antar dokumen
• Review dokumentasi saat sprint review atau milestone
• Minta feedback dari developer baru tentang kelengkapan dokumentasi