Industri teknologi menghadapi masalah berterusan yang telah mengganggu pembangun selama bertahun-tahun. Walaupun dokumentasi teknikal disenaraikan sebagai salah satu daripada tiga sumber pembelajaran utama dalam tinjauan Stack Overflow 2024, kualiti masih kekal mengecewakan. Tinjauan Sumber Terbuka GitHub 2017 mengenal pasti dokumentasi yang tidak lengkap atau mengelirukan sebagai masalah utama bagi pembangun, dan perbincangan komuniti menunjukkan sedikit penambahbaikan sejak itu.
Statistik Utama:
- Dokumentasi teknikal berada dalam kedudukan 3 teratas sebagai sumber pembelajaran ( Stack Overflow survei 2024)
- "Dokumentasi yang tidak lengkap atau mengelirukan" merupakan 1 masalah utama ( GitHub 2017 Open Source Survey )
Masalah Sebenar Bukan Sekadar Kemahiran Menulis
Walaupun ramai menganggap dokumentasi yang lemah berpunca daripada pembangun yang kurang kemahiran menulis, komuniti mendedahkan gambaran yang lebih kompleks. Isu teras nampaknya adalah apa yang dipanggil pakar sebagai masalah minda pemula - pada asasnya kegagalan empati. Pembangun bergelut untuk mengingati bagaimana rasanya sebelum mereka memahami sesuatu konsep, menjadikannya hampir mustahil untuk membimbing orang lain melalui perjalanan pembelajaran yang sama.
Profesional penulisan teknikal menekankan bahawa prosa yang indah tidak bermakna apa-apa jika kandungan tidak melayani khalayak yang dimaksudkan. Cabaran terbesar bukanlah merangka ayat yang elegan, tetapi menganalisis siapa yang akan membaca dokumentasi dan mereka bentuk tepat apa yang mereka perlukan untuk mencapai matlamat mereka. Ini memerlukan pemahaman aliran kerja pengguna, menjangka jurang pengetahuan, dan menyusun maklumat dalam urutan yang logik.
Kebaikan & Keburukan Dokumentasi LLM:
Kelebihan:
- Organisasi struktur yang lebih baik berbanding dokumentasi yang ditulis oleh pembangun
- Pemformatan yang konsisten dan pematuhan templat
- Baik untuk kandungan berformula seperti dokumen reka bentuk
Kelemahan:
- Kandungan lebih sukar untuk diingat dan dikekalkan
- Kurang personaliti dan "suasana" yang menarik
- Mungkin betul secara teknikal tetapi terlepas penjelasan intuitif
Organisasi Yang Berjaya
Sesetengah syarikat telah berjaya melalui taktik psikologi yang bijak. Satu pendekatan melibatkan pasukan dokumentasi khusus yang akan menulis dokumen untuk pembangun yang tidak menyediakan dokumen sendiri. Walau bagaimanapun, pasukan ini sengaja menulis dari perspektif orang luar, memaksa pembangun asal menghabiskan lebih banyak masa untuk menyemak dan membetulkan berbanding masa yang diperlukan untuk menulis dokumentasi yang betul sendiri. Ini mewujudkan insentif yang tepat sambil memastikan output berkualiti.
Penyelesaian Organisasi:
- Kumpulkan maklum balas secara berkala daripada pengguna dokumentasi
- Tambahkan penulis teknikal khusus untuk menyokong pasukan
- Beri perhatian kepada isu berkaitan dokumentasi di GitHub
- Gunakan pasukan dokumentasi "psikologi songsang" yang memaksa penglibatan pembangun
Perdebatan Dokumentasi LLM
Apabila alat kecerdasan buatan menjadi lebih canggih, ramai berharap ia akan menyelesaikan masalah dokumentasi. Sesetengah jurutera melaporkan bahawa dokumen yang dihasilkan LLM mengatasi usaha penulisan teknikal mereka sebelum ini dengan ketara, terutamanya untuk kandungan berstruktur seperti dokumen reka bentuk kejuruteraan rangkaian. Alat ini cemerlang dalam mengikuti templat dan mengekalkan pemformatan yang konsisten.
Walau bagaimanapun, corak yang membimbangkan muncul daripada pengalaman pembangun dengan dokumentasi yang dihasilkan AI . Ramai mendapati kandungan lebih sukar diingati dan kurang menarik berbanding alternatif yang ditulis manusia. Pengoptimuman matematik yang memacu LLM mungkin menghasilkan kandungan yang betul secara teknikal tetapi tidak berjiwa yang tidak mempunyai personaliti dan penjelasan intuitif yang menjadikan konsep teknikal mudah diingati.
AI sama sekali tidak mempunyai gaya dan saya mempunyai tanggapan bahawa banyak perkara yang orang nikmati daripada penulisan teknikal adalah suasana yang mereka dapat daripada penulisan tersebut; sama seperti arahan.
Penyelesaian mungkin melibatkan menganggap dokumentasi sebagai cabaran teknikal dan kreatif. Organisasi memerlukan penulis teknikal khusus, gelung maklum balas tetap dengan pengguna sebenar, dan pembangun yang mengakui bahawa menerangkan idea kompleks memerlukan set kemahiran tersendiri. Walaupun LLM mungkin mengendalikan pemformatan dan struktur, elemen manusia dalam pemahaman dan empati kekal tidak boleh diganti untuk komunikasi teknikal yang benar-benar berkesan.
Rujukan: Let's Talk About Writing in Tech