Peta, Emas dan Rempah: Mengapa Mengabaikan Dokumentasi Boleh Memusnahkan Projek Anda

Apakah aset paling berharga yang dibawa pulang oleh penjelajah zaman dahulu dari pelayaran mereka? Emas dan rempah ratus? salah. Peta.

Christopher Columbus tidak akan pernah melakukan perjalanannya yang terkenal pada tahun 1492 tanpa a peta direka oleh pendahulunya. Permainan pengintip untuk mendapatkan peta Portugis meletakkan asas bagi Syarikat Hindia Timur Belanda, boleh dikatakan syarikat paling mahal dalam sejarah manusia. Pada kemuncaknya pada tahun 1637, ia bernilai 78 juta gulden Belanda, bersamaan dengan $7.9 trilion pada tahun 2017 dolar. Itu adalah lebih daripada $10 trilion dalam wang 2024, lebih daripada Microsoft , Nvidia dan Apple digabungkan . Khazanah yang boleh diraba dari tanah baru adalah penting dalam jangka pendek, tetapi dari perspektif yang lebih panjang, pengetahuanlah yang menempa kekayaan sebenar.

Mengapa dalam dunia teknologi hari ini kita cenderung melupakan perkara ini? Mengejar kejayaan segera, kami sering keberatan untuk memberikan masa dan sumber yang berharga untuk menghasilkan dan menyelenggara dokumentasi teknikal. Bercakap dalam istilah abad ke-17, kami tergesa-gesa untuk merebut emas dan rempah ratus tanpa merancang peta kami yang, seterusnya, boleh membawa kami kepada lebih banyak emas dan rempah ratus. Adakah anda ragu-ragu? Ahoy, mari kita lihat lebih dekat…

Kod aneh

"Seperti yang anda pasti ingat, stasis hipnoid corak neuron otak boleh diimbas oleh pancaran elektromagnet tambahan yang -" "Lepaskan!" kata Ard Vark tidak sabar. "Apa maksud anda - seperti yang kita pasti ingat?" Bagaimana kita boleh mengingatinya sedangkan kita tidak pernah mengetahuinya? – Petikan dari Wacky World ini, sebuah cerita oleh penulis fiksyen sains yang hebat Edmond Hamilton, merujuk kepada orang Marikh, bukan pengaturcara. Walau bagaimanapun, ramai orang melihat pembangun seolah-olah mereka berasal dari planet lain - terutamanya mereka yang hanya mempunyai idea yang samar tentang pembangunan perisian dan kerumitannya. Hakikatnya, pembangun sering menganggap bahawa orang lain tahu kod sama seperti mereka dan sering menganggap dokumentasi teknikal tidak diperlukan. Pemikiran ini berisiko menjadikan projek sebagai kompleks dan tidak dapat difahami oleh orang luar sebagai "stasis hipnoid," akhirnya menjejaskan potensi kejayaan projek.

Keengganan untuk membuat dokumentasi selalunya berpunca daripada sebab yang sama orang menangguhkan di kawasan lain: ia memerlukan masa dan pelaburan kewangan yang besar. Dalam erti kata lain, ia selalunya disebabkan oleh kemalasan semata-mata dan keinginan untuk menjimatkan wang, yang bukan halangan mudah untuk diatasi. Walau bagaimanapun, dokumentasi bukan sekadar maklumat berlebihan yang kononnya jelas kepada semua orang; ia mengandungi butiran kritikal yang boleh menjadi sangat diperlukan. Selalunya, ketiadaan dokumentasi secara ketara merumitkan pengesanan dan pembetulan ralat, menjadikan penyelenggaraan dan kemas kini lebih sukar, dan meningkatkan masa yang diperlukan untuk memasukkan ahli pasukan baharu. Walaupun pasukan tanpa dokumentasi terperangkap melakukan tugasan berulang, projek dengan dokumentasi yang tersusun dengan baik menunjukkan kecekapan dan kebolehpercayaan yang tinggi—ini adalah fakta, bukan pendapat semata-mata.

Ya, sesetengah pengaturcara mendakwa bahawa kod yang mereka tulis sangat jelas dan mudah difahami sehinggakan dokumentasi tidak diperlukan. Walau bagaimanapun, pada hakikatnya, walaupun kod yang paling sempurna boleh mengelirukan orang lain atau kehilangan kejelasannya dari semasa ke semasa. Apa yang kelihatan jelas hari ini boleh menjadi teka-teki esok. Sebagai contoh, bolehkah anda berurusan dengan kad tebuk ringkas dari tahun 70-an?

Faktor bas, Burnout dan binatang hebat lain

Teori bagus, tetapi amalan lebih meyakinkan. Berikut ialah beberapa contoh, berdasarkan kisah benar, dengan hanya nama orang dan syarikat rekaan. Kajian kes ringkas ini merangkumi masalah paling tipikal yang timbul disebabkan oleh amalan dokumentasi teknikal yang lemah.

Cerita #1: Ketidakupayaan untuk Skala

Projek "NoDocumentationPlease," pada mulanya merupakan permulaan penstriman video yang berjaya, menghadapi masalah serius apabila cuba membuat skala kerana dokumentasi teknikal yang lemah. Apabila pasukan perlu berkembang, pekerja baharu tidak dapat memahami sepenuhnya tugas mereka dan tiada siapa yang dapat memberikan penjelasan yang mencukupi kepada mereka. Tanpa sokongan dan latihan yang sewajarnya, pekerja baharu segera pergi. Ini bukan sahaja memperlahankan kemajuan projek tetapi juga membawa kepada kehilangan bakat utama, akhirnya menjejaskan keberkesanan keseluruhan projek dan masa depan. Akibatnya, penstrim meninggalkan sembang dan projek itu telah ditutup.

Cerita #2: Isu penyelenggaraan

Syarikat "IKnowEverything" membangunkan platform awan untuk penyegerakan dan penyimpanan data. Pada mulanya, projek itu berjalan dengan pantas, tetapi lama kelamaan, pembangunnya menghadapi kesukaran untuk menyelenggara dan mengemas kini platform kerana kekurangan dokumentasi teknikal yang jelas dan terkini. Ini membawa kepada pembangunan yang lebih perlahan, lebih banyak pepijat dan pelanggan yang tidak berpuas hati. Akhirnya, syarikat itu mula kehilangan pelanggan lamanya, dan pelanggan baharu memilih pesaing dengan penyelesaian yang lebih stabil dan boleh dipercayai. Hasil menurun dengan ketara manakala kos penyelenggaraan yang tidak berkesan meningkat. Mendokumentasikan aspek teknikal dengan betul dari awal boleh membolehkan mereka membuat skala dengan jayanya. Walau bagaimanapun, ia tidak dilakukan dalam masa. Akibatnya, syarikat tidak dapat mengatasi cabaran teknikal dan kewangan dan telah ditutup.

Cerita #3: Pembangun Burnout

Projek "SmartestEver" menghadapi isu yang teruk kerana pembangun utamanya, Andrew, yang mengendalikan hampir segala-galanya, meletak jawatan selepas terharu dengan pelbagai soalan pasukan. Sekiranya "SmartestEver" mempunyai dokumentasi yang betul, pembangun junior boleh dengan mudah merujuk kepada Soalan Lazim dan menyelesaikan isu rutin. Sebaliknya, mereka membombardir Andrew dengan soalan, dan tanpa dia dan dokumentasi yang diperlukan, pasukan itu gagal untuk meneruskan dan projek itu ditutup (tekan F untuk Andrew).

Cerita #4: Faktor Bas

Dalam syarikat "NoDocsNeeded," produk perisian yang menjanjikan sedang dibangunkan oleh John, pembangun utama, yang memegang semua pengetahuan tetapi tidak peduli untuk mendokumentasikannya. Pengurusnya juga tidak bersusah payah memujuknya. Tibalah hari apabila John pergi dalam perjalanan perniagaan dan tidak pulang. Tanpa dokumentasi atau pemahaman tentang seni bina dan logik produk, ahli pasukan yang tinggal pada dasarnya tidak boleh berbuat apa-apa. Projek itu dibekukan, dan wang yang dilaburkan di dalamnya telah dibazirkan. Pengajarannya mudah: dokumentasi dan pengedaran pengetahuan dalam satu pasukan adalah penting untuk mengelakkan pergantungan kepada seorang sahaja. By the way, mereka masih mencari John…

Kisah #5: Tiada nabi dialu-alukan di Sumber Terbuka

Maria mencipta perpustakaan sumber terbuka pertamanya tetapi tidak menulis sebarang dokumentasi untuknya. Tiada siapa yang memahami apa yang dilakukan oleh perpustakaan itu, dan Maria memutuskan dia tidak akan menulis lagi perpustakaan kerana baginya ia seolah-olah tidak berguna. Projek Maria berakhir sebelum ia bermula dan dia memutuskan untuk menukar profesionnya.

Dari budak kabin kepada kapten

Ok, kami mendapat beberapa teori dan amalan, sekarang mari kita menyelami penyelidikan dan statistik. Tinjauan Pembangun Limpahan Tindanan 2024 negeri bahawa 84% responden menggunakan dokumentasi teknikal untuk memahami kefungsian teknologi. Walau bagaimanapun, walaupun dengan dokumentasi, mereka selalunya tidak dapat mencari jawapan yang mereka perlukan, seperti yang ditunjukkan oleh sumber paling popular seterusnya: Stack Overflow (80%), Tutorial Bertulis (68%), blog (61%) dan How-to video (54%). Penyelidikan Microsoft: Kehidupan Harian Pembangun Perisian dijumpai bahawa, secara purata, pembangun menghabiskan 1-2% daripada hari mereka (8-10 minit) untuk dokumentasi, dan 10.3% daripada pembangun mengatakan dokumentasi lapuk memaksa mereka menghabiskan terlalu banyak masa mencari jawapan sendiri. Keperluan dokumentasi adalah kebimbangan utama bagi komuniti akademik juga. Carian Google Scholar yang mudah untuk <"dokumentasi" DAN "perisian"> hasil lebih 4 juta hasil, dengan jelas menunjukkan sejumlah besar penerbitan saintifik yang menangani isu tersebut.

Kesimpulan utama adalah sangat mudah: #1 – Semua orang memerlukan dokumentasi apabila ia datang untuk memahami teknologi dan/atau kerja orang lain; tetapi #2 - Sedikit orang yang bersusah payah menulis dan mengekalkannya; dan akibatnya #3 – Banyak dokumentasi ditulis dengan buruk, ketinggalan zaman dan secara amnya tidak berguna. Jadi apa yang perlu dilakukan? Ubah motivasi anda di semua peringkat.

Sekumpulan penyelidik dari HAN University of Applied Sciences dan University of Groningen (kedua-duanya di Belanda) dikenalpasti masalah paling biasa dengan dokumentasi teknikal:

• Dokumentasi tidak formal yang sering digunakan oleh pembangun sukar difahami;

• Dokumentasi dianggap sebagai pembaziran apabila ia tidak serta-merta menyumbang kepada produk akhir;

• Produktiviti pembangun diukur dengan jumlah perisian yang berfungsi sahaja;

• Dokumentasi selalunya tidak selari dengan perisian sebenar;

• Pembangun selalunya hanya memberikan tumpuan jangka pendek, terutamanya dalam persekitaran pembangunan perisian yang berterusan.

  
  

Adakah mana-mana ini terdengar biasa? Saya boleh bertaruh kebanyakan daripada kita terserempak dengan kebanyakan atau malah kesemuanya sekali gus dalam rutin kerja harian kita. Dan terdapat lebih daripada itu daripada sekadar penangguhan atau kekurangan sumber. Beberapa masalah ini datang daripada kekurangan pengurusan yang betul, perancangan jangka panjang, dan, akhirnya, visi strategik. Dan inilah bahagian yang sukar, kerana ia bukan hanya terpulang kepada kami, pemaju untuk menyelesaikannya. Sesetengah isu harus ditangani oleh pengurus, pihak berkepentingan produk, malah pemilik syarikat. Itulah sebabnya adalah penting bahawa pandangan yang betul tentang teknikal bukan sekadar aksesori yang bagus, tetapi sebahagian daripada nilai teras keseluruhan syarikat, dikongsi oleh semua orang daripada pengasas kepada pembangun junior.