Keuntungan:
- Keupayaan untuk menghasilkan draf README, docstring dan changelog berdasarkan khalayak sasaran dan sumber dengan AI
- Keupayaan untuk memisahkan lapisan 'apa/bagaimana' dan 'mengapa' dalam dokumentasi dan menambah 'mengapa' sebagai manusia
- Mengesahkan langkah pemasangan dengan menjalankannya secara peribadi dan menjadikan dokumen sebagai sebahagian daripada perubahan kod
Bahagian perisian yang paling kerap diabaikan tetapi tahan lama ialah dokumentasi. Kod itu boleh dibaca walaupun selepas berbulan-bulan; Orang yang menulisnya sudah tiada, konteksnya dilupakan, dan hanya tinggal apa yang ditulis. README yang baik (dokumen pengenalan yang menerangkan maksud projek dan cara memasang serta menjalankannya), komen kod penerangan dan dokumentasi API terkini (rujukan yang menerangkan cara menggunakan antara muka) secara langsung menentukan kelajuan pasukan. AI mengambil banyak "keletihan menulis" daripada dokumentasi — tetapi ia datang dengan perangkap: AI boleh membuat kesimpulan daripada kod apa yang dilakukannya, tetapi selalunya tidak tahu mengapa ia dilakukan dengan cara itu.
Dalam unit ini, anda akan belajar cara menghasilkan README, ulasan kod, docstring (blok ulasan yang ditulis setiap fungsi/kelas), dokumen API dan log perubahan dengan AI; dan cara memelihara bahagian dokumentasi yang paling berharga secara manusiawi: "mengapa."
Perbezaan antara "Apa" dan "Mengapa"
Terdapat dua lapisan dokumentasi. Yang pertama ialah apa/bagaimana: "fungsi ini menyusun senarai", "jalankan arahan ini untuk dipasang". Ini boleh diekstrak daripada kod dan struktur; AI cemerlang di sini. Kedua, mengapa: "mengapa kami menjadikan perkhidmatan ini tidak segerak dan bukannya segerak", "mengapa nilai had ini 30 saat", "mengapa kami memilih perpustakaan ini berbanding yang lain". Ini tidak ditulis dalam kod; Ia adalah produk keputusan reka bentuk, kekangan, dan kesakitan masa lalu.
AI tidak tahu "mengapa"; Paling baik, ia membuat tekaan yang munasabah—yang berbahaya, kerana sebab yang salah adalah lebih buruk daripada tiada sebab sama sekali. Jadi pembahagian kerja adalah jelas: AI merangka "apa/bagaimana", anda menambah "mengapa." Komen yang paling berharga ialah komen yang mengatakan perkara yang tidak boleh dikatakan oleh kod itu.
Petua: Jangan ulangi dengan mengulas perkara yang dinyatakan dengan jelas oleh kod itu sendiri (seperti i = i + 1 // naikkan i dengan satu). AI kadangkala menghasilkan komen berlebihan sedemikian; Hapuskan mereka dan tumpukan tenaga anda untuk komen "mengapa".
Langkah demi Langkah: Penjanaan Dokumentasi dengan AI
- Tentukan khalayak sasaran. "Pembangun yang baru bermula," "pasukan luar yang akan menggunakan API ini," "saya masa depan" — penonton menetapkan nada untuk bahasa dan kedalaman.
- Berikan sumbernya. Tambahkan kod yang berkaitan, README sedia ada, contoh penggunaan pada gesaan. Dokumen tanpa sumber ialah jemputan kepada pemalsuan.
- Struktur pengenaan. Bahagian standard untuk README (Tujuan, Pemasangan, Penggunaan, Konfigurasi, Sumbangan), format projek untuk docstring.
- Tandakan ruang "mengapa". Minta AI untuk menandai keputusan yang ia tidak mengetahui rasionalnya sebagai "nota 'mengapa' diperlukan di sini"; Kemudian anda mengisi tempat kosong tersebut.
- Sahkan. Sebenarnya jalankan langkah pemasangan; cuba kod sampel. README yang tidak berfungsi adalah lebih teruk daripada tiada README sama sekali.
Tiga Kes Mini
Kes 1 — README mempercepatkan onboarding. README alat sumber terbuka tiada; Penyumbang baharu bergelut dengan pemasangan selama purata 2 jam. Pasukan memberikan skrip pemasangan dan package.json kepada AI dan merangka README berstruktur, kemudian menjalankan langkah itu sendiri pada mesin yang bersih dan menambah dua kebergantungan yang hilang. Masa pemasangan untuk penyumbang berikutnya berkurangan kepada purata 25 minit.
Kes 2 — Perangkap "mengapa" yang dibuat-buat. Seorang pembangun meminta AI untuk komen di sebelah nilai tamat masa (masa tamat=30). AI menulis justifikasi yang munasabah tetapi salah "untuk bertolak ansur dengan kependaman rangkaian tinggi"; sebab sebenar ialah had kontrak 30 saat perkhidmatan hiliran. Tafsiran yang salah menyebabkan pembangun seterusnya meningkatkan nilai secara tidak perlu, yang membawa kepada insiden. Pengajaran: pemilik kod mesti mengesahkan justifikasi.
Kes 3 — Standard Docstring telah menjadi automatik. Modul tambahan dengan 40 fungsi tidak mempunyai docstrings. AI telah diberikan format projek (gaya Google) dan menghasilkan parameter, pemulangan dan perihalan pengecualian untuk setiap fungsi; Pembangun menyemak ini dan membetulkan beberapa pengisytiharan jenis yang salah. Mendokumentasikan 40 fungsi menurun daripada kira-kira setengah hari kepada satu jam.
Empat Templat Boleh Disalin
Draf README berstruktur:
Khalayak sasaran: {{cth. penyumbang baharu}}.Tulis draf README berdasarkan fail di bawah. Bahagian: Tujuan, Ciri, Keperluan, Pemasangan, Operasi, Konfigurasi, Pengujian, Sumbangan. Ekstrak arahan pemasangan/menjalankan daripada fail sebenar; SESUAI. Tandai tempat yang anda tidak pasti dengan "[SAHKAN]". Sumber: {{package.json / scripts / sample code}}
Rujukan Docstring/API:
Tulis docstring kepada fungsi ini dalam format {{project style: Google/NumPy/JSDoc}}: ringkasan pendek, parameter (jenis + makna), pulangan, pengecualian dilemparkan, 1 contoh ringkas. Jangan ulangi apa yang dinyatakan dengan JELAS. Tandai keputusan reka bentuk yang memerlukan "mengapa" sebagai "[KENAPA PERLU]", jangan tulis justifikasi yang direka-reka.{{kod}}
Alih keluar ruang untuk ulasan "mengapa":
Dalam kod ini, pembangun seterusnya mungkin bertanya "mengapa begini?" (nombor ajaib, keputusan luar biasa, penyelesaian). Berikan ulasan SKELETON untuk setiap satu, tetapi biarkan rasionalnya KOSONG; Saya akan mengisi justifikasi.{{kod}}
Pernyataan Changelog/PR:
Tulis {{changelog entry / PR description}} daripada perbezaan di bawah. Format: Apa yang berubah (dalam bahasa pengguna), Mengapa (isu: {{...}}), Perubahan pecah (jika ada), Adakah ia telah diuji. Laraskan jargon teknikal kepada khalayak sasaran.{{diff}}
Gesaan lemah / Gesaan kuat
Lemah: "Tulis README untuk projek ini."
Kuat: "Khalayak sasaran: pembangun mengklon repo ini buat kali pertama. Berdasarkan package.json yang dilampirkan, docker-compose.yml dan folder skrip/, tulis draf README dengan bahagian Tujuan, Keperluan, Pemasangan, Operasi, Pengujian, Sumbangan. Ekstrak arahan daripada fail ini, jangan buat; tandakan di mana-mana yang anda tidak pasti] dengan [VERIFY]."
Versi yang kukuh memberikan khalayak, sumber, struktur dan peraturan "buat itu, tandakannya"; supaya dokumen itu berdasarkan fail sebenar dan tempat yang akan disahkan dapat dilihat dengan jelas.
Jenis dokumen
AI berfungsi dengan baik
Manusia menambah/mengesahkan
Pemasangan README
garis besar langkah
Jalankan langkah dan sahkan
Docstring/API
Struktur, parameter, jenis
Jenis yang betul dan "mengapa"
Ulasan kod
"Apa yang dia buat" ringkasan
"Mengapa ini" justifikasi
Changelog/PR
draf pertama
Kesan dan ketepatan
Keputusan seni bina (ADR)
rangka
Keputusan dan kompromi sebenar
Dokumentasi Memerlukan Penyelenggaraan
Aspek yang paling berbahaya bagi dokumen ialah apabila ia kelihatan benar walaupun ia palsu. Apabila kod berubah dan dokumen tidak dikemas kini, ia secara aktif mengelirukan pembaca. AI memudahkan pengemaskinian: keluarkan perbezaan dan tanya "bahagian dokumen manakah yang dipengaruhi oleh perubahan ini?" anda boleh bertanya. Tetapi proses itulah yang memastikan kemas kini — jadikan kemas kini dokumentasi sebahagian daripada perubahan kod (kriteria penerimaan PR). AI mempercepatkan; Pasukan membina disiplin.
Awas: Jangan terbitkan tanpa mengesahkan langkah pemasangan dalam README. Dokumen "mungkin berfungsi" boleh merosakkan hari pertama pembangun baharu dan menghakis kepercayaan. Jalankan langkah sendiri dalam persekitaran yang bersih.
Kesilapan biasa
- Mendapatkan "mengapa" agar sesuai dengan AI. Pembenaran palsu adalah lebih buruk daripada tiada pembenaran; Pemilik kod harus menulis sebab reka bentuk.
- Tidak mengesahkan langkah pemasangan. README yang tidak berfungsi merosakkan kepercayaan.
- Komen yang tidak perlu mengulangi kod. Ia menghasilkan bunyi bising, mengaburkan tafsiran "mengapa" sebenar.
- Tidak menyatakan khalayak sasaran. Dokumen yang tidak jelas kepada siapa ia ditulis tidak berguna sama ada kepada orang baru atau pakar.
- Mengasingkan kemas kini daripada proses. Jika dokumen tidak dikemas kini dengan kod, ia akan menjadi mengelirukan dengan cepat.
Secara ringkasnya
AI mengambil banyak beban mekanikal daripada dokumentasi: draf pantas README, docstring, rujukan API, changelog dan perihalan PR. Tetapi ia tidak dapat mengetahui "mengapa", yang merupakan lapisan yang paling berharga, dan ia berbahaya untuk membuat ia. Pembahagian kerja adalah jelas: AI menghasilkan "apa/bagaimana", anda menambah "mengapa." Tentukan khalayak, sediakan sumber, kenakan struktur, tandakan tempat untuk dimuatkan dan sahkan setiap langkah pemasangan dengan menjalankannya sendiri. Jadikan dokumentasi sebagai sebahagian daripada perubahan kod.
Tugasan permohonan
Pilih modul atau projek kecil yang dokumentasinya tiada atau ketinggalan zaman. Mula-mula jana garis besar daripada AI dengan templat "draf README berstruktur" (atau docstring); Pastikan anda memberikan sumber dan khalayak sasaran. Kemudian pergi melalui setiap titik di mana AI telah menandai [VERIFY] atau [WHY NEEDED]: sebenarnya jalankan langkah persediaan dan isikan reka bentuk “whys” dengan pengetahuan anda sendiri. Perhatikan berapa banyak langkah yang perlu diperbaiki dan berapa banyak "mengapa" yang anda tambahkan.
senarai semak
- [ ] Dalam dokumentasi, saya membezakan lapisan "apa/bagaimana" dan "mengapa".
- [ ] Saya tidak menjadikan AI sebagai "mengapa", saya menambahnya sendiri.
- [ ] Saya memberikan gesaan kepada khalayak sasaran dan fail sumber sebenar.
- [ ] Saya mengesahkan mata [VERIFY] yang ditandakan oleh AI dengan melaksanakannya secara peribadi.
- [ ] Saya menghapuskan komen yang tidak perlu yang mengulangi kod.
- [ ] Saya membuat kemas kini dokumentasi sebahagian daripada perubahan kod.