Industri teknologi menghadapi masalah yang terus-menerus mengganggu para developer selama bertahun-tahun. Meskipun dokumentasi teknis menempati peringkat sebagai salah satu dari tiga sumber pembelajaran teratas dalam survei Stack Overflow 2024, kualitasnya masih sangat mengecewakan. Survei Open Source GitHub 2017 mengidentifikasi dokumentasi yang tidak lengkap atau membingungkan sebagai masalah utama bagi para developer, dan diskusi komunitas menunjukkan bahwa sedikit yang telah membaik sejak saat itu.
Statistik Kunci:
- Dokumentasi teknis masuk dalam 3 besar sumber pembelajaran ( Stack Overflow survei 2024)
- "Dokumentasi yang tidak lengkap atau membingungkan" merupakan 1 poin masalah ( GitHub Survei Open Source 2017)
Masalah Sebenarnya Bukan Hanya Kemampuan Menulis
Meskipun banyak yang berasumsi bahwa dokumentasi yang buruk berasal dari kurangnya kemampuan menulis developer, komunitas mengungkapkan gambaran yang lebih kompleks. Masalah inti tampaknya adalah apa yang disebut para ahli sebagai masalah beginner's mind - pada dasarnya kegagalan empati. Developer kesulitan mengingat bagaimana rasanya sebelum mereka memahami suatu konsep, sehingga hampir tidak mungkin untuk membimbing orang lain melalui perjalanan pembelajaran yang sama.
Para profesional technical writing menekankan bahwa prosa yang indah tidak berarti apa-apa jika kontennya tidak melayani audiens yang dituju. Tantangan terbesar bukanlah menyusun kalimat yang elegan, tetapi menganalisis siapa yang akan membaca dokumentasi dan merancang persis apa yang mereka butuhkan untuk mencapai tujuan mereka. Ini memerlukan pemahaman alur kerja pengguna, mengantisipasi kesenjangan pengetahuan, dan menyusun informasi dalam urutan yang logis.
Kelebihan & Kekurangan Dokumentasi LLM:
Keunggulan:
- Organisasi struktural yang lebih baik dibandingkan banyak dokumentasi yang ditulis developer
- Format yang konsisten dan kepatuhan terhadap template
- Bagus untuk konten yang bersifat formulaik seperti dokumen desain
Kekurangan:
- Konten lebih sulit diingat dan dipahami
- Kurang memiliki kepribadian dan "nuansa" yang menarik
- Mungkin secara teknis benar tetapi melewatkan penjelasan yang intuitif
Organisasi yang Melakukannya dengan Benar
Beberapa perusahaan telah memecahkan kode melalui taktik psikologis yang cerdas. Satu pendekatan melibatkan tim dokumentasi khusus yang akan menulis dokumen untuk developer yang tidak menyediakan dokumen mereka sendiri. Namun, tim ini sengaja menulis dari perspektif orang luar, memaksa developer asli untuk menghabiskan lebih banyak waktu meninjau dan mengoreksi daripada yang akan mereka habiskan untuk menulis dokumentasi yang tepat sendiri. Ini menciptakan insentif yang tepat sambil memastikan output berkualitas.
Solusi Organisasi:
- Mengumpulkan umpan balik secara berkala dari pengguna dokumentasi
- Menambahkan penulis teknis khusus untuk mendukung tim
- Memperhatikan isu terkait dokumentasi di GitHub
- Menggunakan tim dokumentasi "psikologi terbalik" yang memaksa keterlibatan developer
Perdebatan Dokumentasi LLM
Seiring dengan semakin canggihnya alat kecerdasan buatan, banyak yang berharap mereka akan menyelesaikan masalah dokumentasi. Beberapa engineer melaporkan bahwa dokumen yang dihasilkan LLM secara signifikan mengungguli upaya technical writing mereka sebelumnya, terutama untuk konten terstruktur seperti dokumen desain network engineering. Alat-alat ini unggul dalam mengikuti template dan mempertahankan format yang konsisten.
Namun, pola yang mengkhawatirkan muncul dari pengalaman developer dengan dokumentasi yang dihasilkan AI. Banyak yang merasa kontennya lebih sulit diingat dan kurang menarik dibandingkan alternatif yang ditulis manusia. Optimisasi matematika yang mendorong LLM mungkin menghasilkan konten yang secara teknis benar tetapi tanpa jiwa yang tidak memiliki kepribadian dan penjelasan intuitif yang membuat konsep teknis mudah dipahami.
AI sama sekali tidak memiliki swagger dan saya memiliki gagasan bahwa banyak hal yang dinikmati orang dari technical writing adalah vibe yang mereka dapatkan dari tulisan tersebut; sebanyak instruksinya.
Solusinya kemungkinan melibatkan perlakuan dokumentasi sebagai tantangan teknis dan kreatif. Organisasi membutuhkan technical writer khusus, loop umpan balik reguler dengan pengguna sebenarnya, dan developer yang menyadari bahwa menjelaskan ide-ide kompleks memerlukan keterampilan tersendiri. Meskipun LLM mungkin menangani format dan struktur, elemen manusia berupa pemahaman dan empati tetap tidak tergantikan untuk komunikasi teknis yang benar-benar efektif.
Referensi: Let's Talk About Writing in Tech