Keuntungan:
- Kemampuan untuk menghasilkan draf README, docstring, dan changelog berdasarkan target audiens dan sumber dengan AI
- Kemampuan untuk memisahkan lapisan 'apa/bagaimana' dan 'mengapa' dalam dokumentasi dan menambahkan 'mengapa' sebagai manusia
- Memverifikasi langkah-langkah instalasi dengan menjalankannya secara pribadi dan menjadikan dokumen sebagai bagian dari perubahan kode
Bagian perangkat lunak yang paling sering diabaikan namun paling bertahan lama adalah dokumentasi. Kode ini dapat dibaca bahkan setelah berbulan-bulan; Yang menulisnya sudah tiada, konteksnya terlupakan, dan hanya yang tertulis yang tersisa. README yang baik (dokumen pengantar yang menjelaskan apa itu proyek dan cara menginstal serta menjalankannya), komentar kode penjelasan, dan dokumentasi API terkini (referensi yang menjelaskan cara menggunakan antarmuka) secara langsung menentukan kecepatan sebuah tim. AI menghilangkan banyak “kelelahan menulis” dari dokumentasi — namun ada jebakannya: AI dapat menyimpulkan dari kode apa yang dilakukannya, namun sering kali tidak mengetahui mengapa hal itu dilakukan seperti itu.
Pada unit ini, Anda akan mempelajari cara membuat README, komentar kode, docstring (blok komentar yang ditulis per fungsi/kelas), dokumen API, dan changelog dengan AI; dan bagaimana melestarikan bagian dokumentasi yang paling berharga secara manusiawi: “mengapa”.
Perbedaan antara “Apa” dan “Mengapa”
Ada dua lapisan dokumentasi. Yang pertama adalah apa/bagaimana: "fungsi ini mengurutkan daftar", "jalankan perintah ini untuk menginstal". Ini dapat diambil dari kode dan struktur; AI unggul di sini. Kedua, mengapa: "mengapa kami membuat layanan ini asinkron daripada sinkron", "mengapa nilai batas ini 30 detik", "mengapa kami memilih perpustakaan ini daripada yang lain". Ini tidak tertulis dalam kode; Ini adalah produk dari keputusan desain, kendala, dan kesulitan di masa lalu.
AI tidak tahu "mengapa"; Paling-paling, ini merupakan tebakan yang masuk akal—dan ini berbahaya, karena alasan yang salah lebih buruk daripada tidak ada alasan sama sekali. Jadi pembagian kerjanya jelas: AI merancang “apa/bagaimana”, Anda menambahkan “mengapa”. Komentar yang paling berharga adalah komentar yang menyatakan apa yang tidak dapat diungkapkan oleh kode.
Tip: Jangan ulangi dengan komentar apa yang dikatakan dengan jelas oleh kode itu sendiri (seperti i = i + 1 // tambah i satu per satu). AI terkadang menghasilkan komentar yang berlebihan; Hilangkan mereka dan curahkan energi Anda pada komentar “mengapa”.
Langkah demi Langkah: Pembuatan Dokumentasi dengan AI
- Tentukan target audiens. “Pengembang yang baru memulai”, “tim eksternal yang akan menggunakan API ini”, “saya di masa depan” — audiens menentukan gaya bahasa dan kedalamannya.
- Berikan sumbernya. Tambahkan kode yang relevan, README yang ada, contoh penggunaan ke prompt. Dokumen yang tidak bersumber adalah undangan untuk melakukan pemalsuan.
- Struktur pengenaan. Bagian standar untuk README (Tujuan, Instalasi, Penggunaan, Konfigurasi, Kontribusi), format proyek untuk docstring.
- Tandai spasi "mengapa". Minta AI untuk menandai keputusan yang tidak diketahui alasannya sebagai "catatan 'mengapa' diperlukan di sini"; Kemudian Anda mengisi bagian yang kosong itu.
- Memeriksa. Jalankan langkah instalasi sebenarnya; coba kode contoh. README yang tidak berfungsi lebih buruk daripada tidak ada README sama sekali.
Tiga Kasus Mini
Kasus 1 — README mempercepat orientasi. README alat sumber terbuka tidak ada; Kontributor baru berjuang dengan instalasi selama rata-rata 2 jam. Tim memberikan skrip instalasi dan package.json ke AI dan menyusun README terstruktur, kemudian menjalankan langkah-langkahnya sendiri pada mesin yang bersih dan menambahkan dua dependensi yang hilang. Waktu instalasi untuk kontributor selanjutnya berkurang menjadi rata-rata 25 menit.
Kasus 2 - Jebakan “mengapa” yang dibuat-buat. Seorang pengembang meminta AI untuk memberikan komentar di samping nilai batas waktu (timeout=30). AI menulis pembenaran yang masuk akal tetapi salah "untuk mentolerir latensi jaringan yang tinggi"; alasan sebenarnya adalah batas 30 detik kontrak layanan hilir. Salah penafsiran menyebabkan pengembang berikutnya meningkatkan nilai secara tidak perlu, sehingga menyebabkan insiden. Pelajaran: pemilik kode harus memverifikasi pembenarannya.
Kasus 3 — Standar Docstring telah menjadi otomatis. Modul tambahan dengan 40 fungsi tidak memiliki dokumen. AI diberi format proyek (gaya Google) dan menghasilkan deskripsi parameter, pengembalian, dan pengecualian untuk setiap fungsi; Pengembang meninjaunya dan memperbaiki beberapa deklarasi tipe yang salah. Mendokumentasikan 40 fungsi berkurang dari sekitar setengah hari menjadi satu jam.
Empat Templat yang Dapat Disalin
Draf README terstruktur:
Target pemirsa: {{mis. kontributor baru}}.Tulis draf README berdasarkan file di bawah ini. Bagian: Tujuan, Fitur, Persyaratan, Instalasi, Pengoperasian, Konfigurasi, Pengujian, Kontribusi. Ekstrak perintah instalasi/jalankan dari file sebenarnya; TEPAT. Tandai tempat-tempat yang Anda tidak yakin dengan "[VERIFIKASI]". Sumber: {{package.json / scripts / kode contoh}}
Referensi Docstring/API:
Tulis docstring ke fungsi-fungsi ini dalam format {{project style: Google/NumPy/JSDoc}}: ringkasan singkat, parameter (tipe + arti), pengembalian, pengecualian yang diberikan, 1 contoh singkat. Jangan ulangi apa yang dikatakan kode tersebut dengan JELAS. Tandai keputusan desain yang memerlukan "mengapa" sebagai "[MENGAPA DIPERLUKAN]", jangan menulis pembenaran yang dibuat-buat.{{code}}
Hapus spasi untuk komentar "mengapa":
Dalam kode ini, pengembang berikutnya mungkin bertanya "mengapa demikian?" (angka ajaib, keputusan yang tidak biasa, solusi). Berikan komentar SKELETON untuk masing-masingnya, namun biarkan alasannya KOSONG; Saya akan mengisi justifikasinya.{{code}}
Catatan perubahan/pernyataan PR:
Tulis {{entri changelog / deskripsi PR}} dari perbedaan di bawah. Format: Apa yang berubah (dalam bahasa pengguna), Mengapa (masalah: {{...}}), Perubahan yang dapat menyebabkan gangguan (jika ada), Apakah sudah diuji. Sesuaikan jargon teknis dengan target audiens.{{diff}}
Perintah lemah / Perintah kuat
Lemah: "Tulis README untuk proyek ini."
Kuat: "Target audiens: pengembang mengkloning repo ini untuk pertama kalinya. Berdasarkan folder package.json, docker-compose.yml dan scripts/ terlampir, tulis draf README dengan bagian Tujuan, Persyaratan, Instalasi, Operasi, Pengujian, Kontribusi. Ekstrak perintah dari file-file ini, jangan dibuat-buat; tandai di mana pun Anda tidak yakin dengan [VERIFY]."
Versi yang kuat memberikan audiens, sumber, struktur, dan aturan “buat, tandai”; sehingga dokumen tersebut berdasarkan file asli dan tempat yang akan diverifikasi terlihat jelas.
Jenis dokumen
AI bekerja dengan baik
Manusia menambahkan/memverifikasi
Instalasi README
garis besar langkah
Jalankan langkah-langkahnya dan konfirmasi
Dokumen/API
Struktur, parameter, tipe
Jenis yang benar dan "mengapa"
Komentar kode
Ringkasan "Apa yang dia lakukan".
Pembenaran "Mengapa ini".
Catatan Perubahan/PR
draf pertama
Dampak dan akurasi
Keputusan arsitektur (ADR)
kerangka
Keputusan dan kompromi nyata
Dokumentasi Membutuhkan Pemeliharaan
Aspek yang paling berbahaya dari sebuah dokumen adalah ketika dokumen tersebut terlihat benar padahal sebenarnya palsu. Ketika kode berubah dan dokumen tidak diperbarui, hal itu secara aktif menyesatkan pembaca. AI mempermudah pembaruan: keluarkan perbedaan dan tanyakan “bagian mana dari dokumen yang terpengaruh oleh perubahan ini?” Anda mungkin bertanya. Namun proseslah yang memastikan kemutakhiran — jadikan pembaruan dokumentasi sebagai bagian dari perubahan kode (kriteria penerimaan PR). AI berakselerasi; Tim membangun disiplin.
Perhatian: Jangan publikasikan tanpa memverifikasi langkah-langkah instalasi di README. Dokumen yang "mungkin berhasil" dapat merusak hari pertama pengembang baru dan mengikis kepercayaan. Jalankan sendiri langkah-langkahnya di lingkungan yang bersih.
Kesalahan umum
- Mendapatkan “mengapa” agar sesuai dengan AI. Pembenaran yang salah lebih buruk daripada tidak adanya pembenaran; Pemilik kode harus menulis alasan desain.
- Tidak memverifikasi langkah-langkah instalasi. README yang tidak berfungsi menghancurkan kepercayaan.
- Komentar yang tidak perlu mengulangi kode. Ini menghasilkan kebisingan, mengaburkan interpretasi “mengapa” yang sebenarnya.
- Tidak menentukan target audiensnya. Sebuah dokumen yang tidak jelas kepada siapa dokumen itu ditulis tidak ada gunanya baik bagi pemula maupun ahli.
- Memisahkan pembaruan dari proses. Jika dokumen tidak diperbarui dengan kode, maka dokumen tersebut akan cepat menyesatkan.
Singkatnya
AI menghilangkan sebagian besar beban mekanis dari dokumentasi: draf cepat README, docstring, referensi API, changelog, dan deskripsi PR. Tapi ia tidak bisa mengetahui "mengapa", yang merupakan lapisan paling berharga, dan berbahaya untuk mengada-ada. Pembagian kerjanya jelas: AI menghasilkan “apa/bagaimana”, Anda menambahkan “mengapa”. Tentukan audiens, sediakan sumber daya, terapkan struktur, tandai tempat yang sesuai, dan verifikasi setiap langkah instalasi dengan menjalankannya sendiri. Jadikan dokumentasi sebagai bagian integral dari perubahan kode.
Tugas aplikasi
Pilih modul atau proyek kecil yang dokumentasinya hilang atau ketinggalan jaman. Pertama, buat garis besar dari AI dengan templat “draf README terstruktur” (atau docstring); Pastikan untuk memberikan sumber dan target audiens. Kemudian telusuri setiap titik di mana AI telah menandai [VERIFIKASI] atau [MENGAPA DIPERLUKAN]: jalankan langkah-langkah penyiapan sebenarnya dan isi desain “mengapa” dengan pengetahuan Anda sendiri. Catat berapa banyak langkah yang perlu diperbaiki dan berapa banyak “mengapa” yang Anda tambahkan.
daftar periksa
- [ ] Dalam dokumentasi, saya membedakan lapisan "apa/bagaimana" dan "mengapa".
- [ ] Saya tidak menjadikan AI sebagai "mengapa", saya menambahkannya sendiri.
- [ ] Saya memberikan prompt kepada audiens target dan file sumber sebenarnya.
- [ ] Saya memverifikasi poin [VERIFY] yang ditandai oleh AI dengan menjalankannya secara pribadi.
- [ ] Saya menghilangkan komentar yang tidak perlu yang mengulangi kode tersebut.
- [] Saya menjadikan pembaruan dokumentasi sebagai bagian dari perubahan kode.