Skip to main content

Dokumentasi Adalah Bagian dari Produk

Ini bukan hal teknis biasa - ini adalah budaya yang harus dipegang oleh semuanya.

Mengapa Dokumentasi Bukan Pilihan?​

ELJoy adalah proyek yang akan berkembang selama bertahun-tahun. Tim yang mengerjakannya mungkin akan berubah. Anggota baru akan bergabung. Anggota lama mungkin meninggalkan tim. Keputusan yang diambil hari ini mungkin perlu dipahami oleh orang yang berbeda dua tahun dari sekarang.

Tanpa dokumentasi yang baik:

  • Pengetahuan tentang kenapa sebuah keputusan diambil hilang ketika orang yang membuatnya pergi
  • Tim baru menghabiskan waktu berjam-jam mencoba memahami kode yang sudah ada
  • Keputusan yang sama dibuat berulang kali karena tidak ada catatan tentang keputusan sebelumnya
  • Perubahan arsitektur yang "kecil" secara tidak sengaja memecah hal-hal yang sudah bekerja

Apa yang Harus Didokumentasikan?​

Keputusan Arsitektur Mengapa modul dirancang dengan cara tertentu? Mengapa data model menggunakan pendekatan ini, bukan itu? Apa trade-off yang dipertimbangkan? Semua ini harus tercatat.

API Contracts Bagaimana satu modul berkomunikasi dengan modul lain? Input apa yang diharapkan? Output apa yang dijamin? Apa yang terjadi ketika ada error?

Data Model Apa arti setiap field di database? Bagaimana relasi antar tabel? Apa yang boleh null dan apa yang tidak boleh?

Business Rules Bagaimana aturan CEFR Eligibility bekerja? Apa kriteria Evidence of Mastery? Bagaimana algoritma recommendation memilih konten?

Setup dan Deployment Bagaimana cara menjalankan sistem secara lokal? Bagaimana cara deploy? Apa dependency yang diperlukan?

Dokumentasi sebagai Investasi​

Menulis dokumentasi memang memakan waktu. Tapi waktu yang diinvestasikan di dokumentasi akan menghemat waktu yang jauh lebih banyak di masa depan.

Setiap kali seorang anggota tim baru bisa langsung memahami sistem dan mulai berkontribusi dalam satu hari - bukan satu minggu - itulah return on investment dari dokumentasi yang baik.

Dokumentasi Bukan Setelah Selesai Coding​

Ini adalah kesalahan yang sangat umum: dokumentasi dianggap sebagai pekerjaan yang dilakukan setelah coding selesai.

Di ELJoy, dokumentasi adalah bagian dari proses pengembangan - bukan tambahan di akhir. Ketika sebuah keputusan arsitektur diambil, dokumentasikan saat itu juga. Ketika sebuah API didesain, dokumentasikan kontraknya sebelum implementasi dimulai.

Dokumentasi yang ditulis pada saat yang tepat adalah dokumentasi yang paling akurat dan paling bermanfaat.