Apa itu Documentation as Code?
Documentation as Code (DaaC) adalah pendekatan yang memperlakukan dokumentasi sebagai bagian tak terpisahkan dari codebase, ditulis oleh engineer, diversikan di Git, di-review, dan diuji dalam pipeline yang sama dengan kode. Panduan ini menjelaskan artinya, alasan tim mengadopsinya, dan tools yang membuatnya bekerja.
Documentation as Code (DaaC) adalah pendekatan yang memperlakukan dokumentasi sebagai bagian tak terpisahkan dari kode. Alih-alih berada di wiki yang terpisah, dokumentasi ditulis oleh engineer, disimpan di version control, di-review layaknya pull request, dan divalidasi otomatis di build pipeline.
“Satu-satunya hal yang lebih buruk daripada tidak ada dokumentasi adalah dokumentasi yang buruk.”
Terdengar sederhana, tetapi ini mengubah seluruh cara dokumentasi ditulis dan dipelihara. Berikut penjelasan apa itu DaaC, kenapa dokumentasi sering usang, bagaimana DaaC memperbaikinya, serta tools dan praktik yang mewujudkannya.
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. Biasanya ada dua anggapan di baliknya:
- Dokumentasi terasa seperti pekerjaan tambahan. Karena dokumentasi dianggap terpisah dari kode, menulisnya terasa seperti beban di luar tugas utama engineer.
- Dokumentasi dianggap tugas Technical Writer. Sebagian benar, tetapi 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 diam-diam 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:
- Menulis dokumentasi adalah tanggung jawab engineer, bukan pelengkap opsional.
- Dokumentasi berada di version control, tepat di samping kode.
- Dokumentasi diperiksa dan diuji format serta validitasnya di dalam build pipeline, sama seperti kode.
- Dokumentasi diagregasi ke satu portal yang bisa dijelajahi dan di-review seluruh tim.
- Dokumentasi yang tidak sesuai diperlakukan sebagai bug: dicatat di tracker, ditugaskan ke engineer, diperbaiki, lalu diperiksa ulang.
Manfaat Documentation as Code
Memperlakukan dokumentasi sebagai kode memberi keuntungan kualitas yang sama seperti praktik engineering yang baik:
- Kolaborasi lebih baik: version control dan code review membuat seluruh tim membuat dan memelihara dokumentasi bersama.
- Pemeliharaan lebih mudah: karena dokumentasi menjadi bagian proses pengembangan, ia tetap mutakhir alih-alih usang.
- Komunikasi lebih baik: portal yang terpusat dan mudah diakses menjembatani engineer dengan pemangku kepentingan non-teknis seperti product manager dan desainer.
- Satu sumber kebenaran: semua orang membaca dokumentasi yang sama, sudah di-review dan diversikan.
Tools Documentation as Code
DaaC memakai ulang tools yang sudah dimiliki tim untuk source code. Stack yang umum meliputi:
- Version control dan CI/CD: Git serta platform seperti GitLab atau GitHub menampung dokumentasi, menjalankan review, dan mem-build-nya di pipeline.
- Linter docstring: tools seperti pydocstyle menegakkan format dan cakupan docstring, menggagalkan build jika cakupan terlalu rendah.
- Generator dokumentasi: Sphinx mengubah docstring menjadi HTML yang bisa dijelajahi.
- Portal dokumentasi dan static site generator: Docsify, MkDocs, Hugo, atau Jekyll mengubah Markdown menjadi situs dokumentasi yang di-host.
- Issue dan bug tracker: tools seperti Redmine atau Jira melacak dokumentasi yang tidak valid, kedaluwarsa, atau keliru sebagai bug.
Best practice Documentation as Code
Beberapa kebijakan sederhana membuat DaaC melekat:
- Tahan merge request jika docstring yang diwajibkan hilang.
- Wajibkan deskripsi tertulis yang jelas: ide, konsep, dan contoh implementasi, untuk setiap fitur baru.
- Simpan dokumentasi di repository yang sama dengan kode yang dijelaskannya agar keduanya berkembang bersama.
- Perlakukan kegagalan dokumentasi sebagai kegagalan build, bukan sekadar pelengkap.
Bagaimana 8grams menerapkan Documentation as Code
Di 8grams, kami menerapkan DaaC dengan tools yang sama seperti untuk source code, Git untuk versioning dan review, pemeriksaan docstring di CI, portal dokumentasi yang di-generate, serta bug tracker untuk masalah dokumentasi. Merge request tidak disetujui bila docstring hilang, sehingga dokumentasi tetap akurat seiring codebase bertumbuh.
Poin penting
- Documentation as Code (DaaC) mengelola dokumentasi dengan tools yang sama seperti source code: version control, review, pengujian, dan CI/CD.
- DaaC mengatasi dokumentasi usang dan hilang dengan menjadikannya tanggung jawab engineer dan bagian dari pipeline.
- Dokumentasi yang tidak sesuai diperlakukan sebagai bug, dilacak, ditugaskan, diperbaiki, dan diperiksa ulang.
- Tools yang umum meliputi Git, linter docstring, Sphinx, dan static site generator seperti Docsify, MkDocs, atau Hugo.
Pertanyaan umum.
Apa itu Documentation as Code (DaaC)?
Documentation as Code adalah praktik menulis, menyimpan, me-review, dan menguji dokumentasi dengan tools dan alur kerja yang sama seperti source code, version control, code review, dan pipeline CI/CD. Dokumentasi berada di samping kode dan diperlakukan sebagai bagian utama software.
Kenapa memperlakukan dokumentasi sebagai kode?
Karena itu menjaga dokumentasi tetap akurat. Saat dokumentasi diversikan, di-review, dan divalidasi di build pipeline seperti kode, ia tetap selaras dengan software alih-alih usang di wiki terpisah.
Apa beda Documentation as Code dengan wiki?
Wiki disunting terpisah dari kode dan mudah usang. Documentation as Code berada di repository yang sama, mengikuti proses review yang sama, dan diuji otomatis, sehingga berkembang bersama kode yang dijelaskannya.
Tools apa yang dipakai untuk Documentation as Code?
Tools yang umum meliputi Git dan GitLab/GitHub untuk version control dan CI, linter docstring seperti pydocstyle, generator seperti Sphinx, static site generator seperti Docsify, MkDocs, Hugo, atau Jekyll, serta issue tracker seperti Redmine atau Jira untuk bug dokumentasi.
Apakah Documentation as Code menggantikan Technical Writer?
Tidak. Technical writer tetap sangat bernilai untuk panduan dan konten yang menghadap pengguna. DaaC hanya membuat engineer bertanggung jawab atas dokumen yang hanya bisa mereka tulis, reference docs dan docstring, dan memberi semua orang satu sumber kebenaran yang sudah di-review.
Bagaimana cara menguji dokumentasi?
Anda me-lint format dan cakupannya (misalnya menggagalkan build jika cakupan docstring turun di bawah ambang), memeriksa tautan dan struktur, serta memperlakukan dokumentasi yang tidak sesuai sebagai bug yang harus diperbaiki sebelum di-merge.
Apa itu docstring?
Docstring adalah dokumentasi yang ditulis langsung di source code untuk menjelaskan modul, kelas, atau fungsi. Tools bisa menegakkan format dan cakupannya serta meng-generate dokumentasi HTML yang bisa dijelajahi darinya.
Bisakah non-developer berkontribusi ke Documentation as Code?
Bisa. Karena sebagian besar konten DaaC ditulis dalam Markdown dan dipublikasikan ke portal, product manager, desainer, dan pemangku kepentingan lain bisa membacanya dengan mudah dan, dengan alur Git ringan, ikut menyunting.
Apakah Documentation as Code hanya untuk API?
Tidak. Ini bekerja untuk reference API, dokumen arsitektur, runbook, panduan onboarding, dan basis pengetahuan internal, apa pun yang diuntungkan dengan diversikan, di-review, dan dijaga selaras dengan kode.
Bagaimana cara memulai Documentation as Code?
Mulai dengan memindahkan dokumentasi ke repository kode, menambahkan linter docstring atau Markdown ke pipeline CI, mempublikasikan portal dokumentasi dengan static site generator, dan menjadikan dokumentasi yang hilang atau tidak valid sebagai penahan merge, lalu berkembang dari sana.
Punya proyek seperti ini?
Ceritakan proyek Anda, kami balas dalam satu hari kerja.
Hubungi 8grams