Selama 15 tahun yang lalu saya telah bekerja pada puluhan projek perisian, dan hampir setiap kali dokumen itu mengerikan. Pengembang meremehkan keperluan untuk dokumentasi kerana mereka fikir mereka sudah memahami segala-galanya. Pengurus meremehkannya kerana mereka menganggap bahawa pemaju hanya boleh membaca kod dan memahami projek dalam beberapa jam. Walaupun orang tidak meremehkan dokumentasi, mereka sering kekurangan masa dan keupayaan untuk itu. gambaran keseluruhan yang tepat dan terkini biasanya terletak di kepala pengembang senior, yang sudah mempunyai banyak tanggungjawab. Tiada budaya atau intuisi yang dikongsi mengenai apa yang perlu didokumentasikan dan apa yang jelas.Pengembang sering menambah komen untuk fungsi-fungsi trivial atau menerangkan parameter apabila nama atau jenis variabel yang lebih jelas akan menyelesaikan masalah. Mungkinkah dokumentasi itu sudah usang? sahaja , menunjukkan ramai pasukan menganggap dokumen sebagai "formaliti opsional" 4% syarikat sentiasa mendokumentasikan proses mereka https://www.bptrends.com/bpt/wp-content/uploads/2015-BPT-Survey-Report.pdf/ Pada masa yang sama, kami mempunyai bukti yang kuat bahawa tanpa dokumen yang baik perniagaan hanya kehilangan sejumlah besar masa dan wang: “Dokumen yang tidak mencukupi” dinyatakan oleh 41% pengembang sebagai punca utama masa yang terbuang, dengan 69% pengembang kehilangan 8+ jam seminggu kepada ketidaksempurnaan sedemikian (yang berjumlah ~$ 18.5M dalam produktiviti tahunan yang hilang per 1,000 pengembang) https://newsletter.getdx.com/p/state-of-developer-experience-2024 Onboarding seorang jurutera baru mengambil masa 3–9 bulan, sangat bergantung kepada dokumentasi https://stripe.com/files/reports/the-developer-coefficient.pdf Kekurangan Dokumen adalah komponen utama hutang teknikal (https://www.informit.com/store/economics-of-software-quality-9780132582209) Sebuah eksperimen dengan lebih daripada 30 pengaturcaraan menunjukkan bahawa kurangnya dokumen menyebabkan kira-kira 21% lebih banyak masa yang dihabiskan untuk memahami kod semasa tugas pemeliharaan https://hci.com.au/get-documentation-budget/ Jadi apa penghalang sebenar di sebalik kekurangan dokumen yang meluas? Dalam kerja cemerlang Andrew Forward “Dokumen Perisian – Membina dan Mengekalkan Artefak Komunikasi” telah melakukan penyelidikan yang baik kepada sebab-sebab sebenar. External Factors Influencing Documentation Quality Seperti yang anda boleh lihat, kekurangan masa dan bajet berkorelasi dengan kekecewaan bahawa usaha dokumentasi boleh menjadi tidak berguna dan cepat usang. Jadi jika kita mengurangkan usaha manual dan menyelesaikan masalah dokumen yang menjadi usang, kita boleh membuat langkah maju yang signifikan. Komuniti pengembang telah memperkenalkan pendekatan seperti Javadoc dan alat serupa yang menghasilkan dokumen secara automatik daripada tanda tangan kod. Oleh itu, kita masih memerlukan dokumen yang ditulis dengan baik, terkini, boleh dibaca oleh manusia. Masalah sebenar ialah bahawa dokumentasi bukan satu-satu kali dihantar tetapi Walaupun pasukan menulis dokumen yang baik pada mulanya, kod berkembang lebih cepat daripada tabiat dokumentasi. tanpa penyegerakan berterusan, dokumentasi menjadi menyesatkan – yang lebih buruk daripada tidak mempunyai apa-apa. Artifak hidup Ini bermakna bahawa botol tidak Dokumen, tetapi . Menulis Mengekalkan yang betul Penyelesaian yang AI sebenarnya baik dalam mencocokkan corak mudah antara kod dan dok. Terdapat beberapa penyelesaian yang baik di mana anda boleh mengotomatiskan pengedaran dokumen melalui AI: Merge request rules, pointing agent to existing documentation and changed code base Claude Code documentation agent that keeps project docs up to date with Docusaurus. npx claude-code-templates@latest --agent=documentation/docusaurus-expert --yes Pendekatan ini berfungsi dengan baik untuk: Memperbarui deskripsi peringkat tinggi Kode Intensifikasi Menulis semula frasa lama Mengembalikan konteks naratif yang hilang Walau bagaimanapun, AI mempunyai batasan yang jelas: Ia berjuang untuk mendeteksi ketidaksesuaian struktural (contohnya, inv vars tanpa dokumen, port, bendera CLI, bendera ciri). Ia boleh berhalusinasi, terutamanya apabila dokumen tidak lengkap atau ambigu. Ia tidak menghasilkan pemeriksaan determinist yang boleh dilacak - setiap run boleh menghasilkan hasil yang sedikit berbeza. Ia tidak boleh mengatakan dengan boleh dipercayai apa yang penting dan apa yang berisik tanpa pengetahuan domain. Dengan kata lain, AI boleh membantu Namun, ia tidak boleh dipercayai sebagai a . rewrite and improve text source of truth validator Pemeriksaan statik Alat-alat seperti menangani masalah ini dengan memperlakukan dokumen sebagai sesuatu yang perlu dipantau secara berterusan, seperti kualiti kod atau drift infrastruktur. ia berfungsi semata-mata secara algoritmik supaya tidak terjejas oleh halusinasi, walaupun positif palsu masih mungkin. Duka Ducku berfungsi dengan mengekstrak isyarat struktur daripada repository anda – variabel persekitaran, laluan API, titik kemasukan perkhidmatan, import modul, struktur direktori, kunci konfigurasi – dan membandingkan mereka dengan apa yang merujuk dalam READMEs dan wiki anda. Keupayaan semasa Pengesahan kehadiran entiti: Mengesan apabila variabel persekitaran, kunci konfigurasi, port, laluan API, atau nama skrip muncul dalam dokumen tetapi tidak dalam kod (dan sebaliknya). Penyampaian entiti paralel: Mengidentifikasi kumpulan item yang serupa (perkhidmatan, pekerjaan ETL, pengendali lambda, perintah CLI) dan menandakan tambahan yang tidak didokumenkan. Analisis modul mati: Mengesan fail yang tidak diimport / digunakan di mana-mana sahaja - sama ada titik kemasukan yang layak penjelasan atau artefak yang usang. Semak integriti URL: Mengesan pautan yang rosak atau lama ke sumber dalaman atau luaran. Konsistensi sihir dan gaya: kebersihan asas yang biasanya diabaikan. Ini sudah cukup untuk mengurangkan sebahagian besar pergerakan dokumen diam dalam projek sebenar. Kesimpulan Dokumen tidak gagal kerana jurutera tidak berhati-hati. yang mengekalkan ia selaras dengan sistem yang ia menerangkan. Kod mempunyai ujian. Infrastruktur mempunyai pengesanan drift. CI mempunyai gerbang dasar. Dokumentasi, dalam kebanyakan pasukan, tidak mempunyai apa-apa. no feedback loop AI boleh meningkatkan frasa dan mengembalikan konteks, tetapi ia tidak boleh mengatakan dengan boleh dipercayai sama ada dokumentasi adalah Kawalan statik, sebaliknya, boleh mengesahkan penyelarasan fakta, tetapi mereka tidak boleh menjelaskan niat atau logik domain. correct Kedua-duanya boleh membawa apa yang anda perlukan.
