Apa itu Documentation as Code?

Apa itu Documentation as Code?

Documentation as Code (DaaC) adalah praktik mengelola dokumentasi dengan tools dan alur kerja yang sudah dipakai engineer untuk source code: version control, code review, pengujian otomatis, dan pipeline CI/CD.

Dalam praktik, dokumentasi disimpan berdampingan dengan kode yang dijelaskannya, dilacak di Git, di-review sebelum di-merge, dan diperiksa otomatis untuk format serta validitasnya. Dokumentasi berhenti menjadi pelengkap di sistem terpisah dan menjadi bagian utama dari software itu sendiri.

Kenapa engineer sering melewatkan dokumentasi?

Tanya siapa pun apakah dokumentasi itu penting, jawabannya hampir selalu ya, namun bahkan engineer yang menghargainya jarang bersemangat menulisnya. Sebagian alasannya, dokumentasi terasa seperti pekerjaan tambahan: karena dianggap terpisah dari kode, menulisnya terasa seperti beban di luar tugas utama engineer.

Sebagian lagi karena anggapan diam-diam bahwa dokumentasi adalah tugas Technical Writer. Itu hanya separuh benar, sebab ada dokumen, seperti reference docs dan docstring, yang hanya bisa ditulis oleh engineer yang membangun fitur itu. Akibatnya, dokumentasi menjadi usang, tidak lengkap, atau hilang sama sekali, yang perlahan menggerus kualitas dan kemudahan pemeliharaan software.

Bagaimana Documentation as Code bekerja

DaaC menutup jurang antara pentingnya dokumentasi dan kenyataan cara penulisannya dengan satu pernyataan: dokumentasi adalah bagian dari kode. Kalimat sederhana ini mengubah cara dokumentasi diperlakukan. Menulisnya menjadi tanggung jawab engineer, bukan pelengkap opsional, dan dokumentasi berada di version control tepat di samping kode yang dijelaskannya.

Dari sana, dokumentasi diperiksa dan diuji format serta validitasnya di dalam build pipeline, sama seperti kode, lalu diagregasi ke satu portal yang bisa dijelajahi dan di-review seluruh tim. Ketika dokumentasi hilang atau tidak sesuai, ia diperlakukan sebagai bug: dicatat di tracker, ditugaskan ke engineer, diperbaiki, dan diperiksa ulang sebelum dianggap selesai.

Manfaat Documentation as Code

Memperlakukan dokumentasi sebagai kode memberi keuntungan kualitas yang sama seperti praktik engineering yang baik. Version control dan code review membuat seluruh tim membuat dan memelihara dokumentasi bersama alih-alih satu orang menjaga wiki yang usang, dan karena dokumentasi menjadi bagian proses pengembangan, ia tetap mutakhir alih-alih ketinggalan.

Ini juga memperbaiki komunikasi di luar tim engineering. Portal yang terpusat dan mudah dicari menjembatani engineer dengan pemangku kepentingan non-teknis seperti product manager dan desainer, dan semua orang membaca sumber kebenaran yang sama, sudah di-review dan diversikan.

Tools Documentation as Code

DaaC memakai ulang tools yang sudah dimiliki tim untuk source code. Git dan platform seperti GitLab atau GitHub menampung dokumentasi, menjalankan review, dan mem-build-nya di pipeline CI/CD yang sama dengan kode. Docstring ditegakkan dengan linter seperti pydocstyle, yang memastikan setiap modul dan fungsi terdokumentasi dalam format yang benar dan menggagalkan build jika cakupannya turun di bawah ambang tertentu.

Generator seperti Sphinx kemudian mengubah docstring itu menjadi HTML yang bisa dijelajahi, yang bisa di-build menjadi image dan di-deploy ke subdomain internal. Untuk menyatukan semuanya, portal dokumentasi yang dibangun dengan Docsify, atau static site generator seperti MkDocs, Hugo, atau Jekyll, mengubah Markdown menjadi situs yang bisa dibaca seluruh tim. Terakhir, bug tracker seperti Redmine mencatat dokumentasi yang tidak valid, kedaluwarsa, atau keliru sebagai isu, dengan tracker khusus per proyek.

Best practice Documentation as Code

Beberapa kebijakan sederhana membuat DaaC melekat. Di 8grams kami mengikuti aturan tak tertulis bahwa merge request tidak disetujui atau di-merge selama docstring yang diwajibkan masih hilang, dan setiap engineer diharapkan menulis deskripsi yang jelas, mencakup ide, konsep, dan contoh implementasi, saat membangun sebuah fitur.

Dua kebiasaan menjaga standar tetap terjaga: simpan dokumentasi di repository yang sama dengan kode yang dijelaskannya agar keduanya berkembang bersama, dan perlakukan kegagalan dokumentasi sebagai kegagalan build, bukan sekadar pelengkap.

Bagaimana 8grams menerapkan Documentation as Code

Hasilnya adalah dokumentasi yang bisa Anda percaya. Karena diversikan, di-review, dan diuji seperti kode, dokumentasi tetap akurat seiring codebase bertumbuh, dan engineer baru bisa onboarding dari satu sumber kebenaran alih-alih menyusun pengetahuan yang tersebar.