Peta, Emas dan Rempah: Mengapa Mengabaikan Dokumentasi Dapat Menghancurkan Proyek Anda

Apa aset paling berharga yang dibawa pulang para penjelajah zaman dahulu dari pelayaran mereka? Emas dan rempah-rempah? Salah. Peta.

Christopher Columbus tidak akan pernah melakukan perjalanan terkenalnya pada tahun 1492 tanpa peta dirancang oleh para pendahulunya. Sebuah permainan mata-mata untuk mendapatkan peta Portugis meletakkan dasar bagi Perusahaan Hindia Timur Belanda, yang bisa dibilang perusahaan termahal dalam sejarah manusia. Pada puncaknya pada tahun 1637, perusahaan ini bernilai 78 juta gulden Belanda, setara dengan $7,9 triliun dalam dolar tahun 2017. Itu lebih dari $10 triliun dalam uang tahun 2024, lebih dari Microsoft , Nvidia, dan Apple gabungan Harta karun yang nyata dari negeri baru penting dalam jangka pendek, tetapi dalam jangka panjang, pengetahuanlah yang menghasilkan kekayaan nyata.

Bagaimana mungkin di dunia teknologi saat ini kita cenderung melupakan hal ini? Mengejar kesuksesan instan, kita sering kali enggan untuk mengalokasikan waktu dan sumber daya yang berharga untuk membuat dan memelihara dokumentasi teknis. Berbicara dalam istilah abad ke-17, kita terburu-buru untuk meraup emas dan rempah-rempah tanpa memetakannya, yang pada gilirannya dapat membawa kita ke lebih banyak emas dan rempah-rempah. Apakah Anda skeptis? Ahoy, mari kita lihat lebih dekat…

Kode aneh

“Seperti yang Anda ingat, stasis hipnoid dari pola neuron otak dapat dipindai oleh sinar ekstra-elektromagnetik yang –” “Hentikan!” kata Ard Vark tidak sabar. “Apa maksud Anda – seperti yang kita ingat?” Bagaimana kita bisa mengingatnya jika kita tidak pernah mengetahuinya? – Kutipan dari Wacky World ini, sebuah cerita oleh penulis fiksi ilmiah hebat Edmond Hamilton, merujuk pada orang Mars, bukan programmer. Namun, banyak orang memandang pengembang seolah-olah mereka berasal dari planet lain – terutama mereka yang hanya memiliki gambaran samar tentang pengembangan perangkat lunak dan kompleksitasnya. Faktanya, pengembang sering kali berasumsi bahwa orang lain mengetahui kode sebaik mereka dan sering kali menganggap dokumentasi teknis tidak diperlukan. Pola pikir ini berisiko membuat proyek menjadi serumit dan tidak dapat dipahami oleh orang luar seperti "stasis hipnoid", yang pada akhirnya membahayakan potensi keberhasilan proyek.

Keengganan untuk membuat dokumentasi sering kali berasal dari alasan yang sama dengan orang yang menunda-nunda di bidang lain: hal itu memerlukan waktu dan investasi finansial yang signifikan. Dengan kata lain, hal itu sering kali disebabkan oleh kemalasan belaka dan keinginan untuk menghemat uang, yang bukanlah hambatan yang mudah untuk diatasi. Namun, dokumentasi bukan hanya informasi berulang yang seharusnya jelas bagi semua orang; dokumentasi berisi detail penting yang mungkin sangat diperlukan. Sering kali, tidak adanya dokumentasi secara signifikan mempersulit pendeteksian dan perbaikan kesalahan, membuat pemeliharaan dan pembaruan menjadi lebih sulit, dan meningkatkan waktu yang dibutuhkan untuk menerima anggota tim baru. Sementara tim tanpa dokumentasi terjebak melakukan tugas-tugas yang berulang, proyek-proyek dengan dokumentasi yang terstruktur dengan baik menunjukkan efisiensi dan keandalan yang tinggi—ini adalah fakta, bukan sekadar pendapat.

Ya, beberapa programmer mengklaim bahwa kode yang mereka tulis sangat jelas dan mudah dipahami sehingga dokumentasi tidak diperlukan. Namun, pada kenyataannya, bahkan kode yang paling sempurna pun dapat membingungkan orang lain atau kehilangan kejelasannya seiring berjalannya waktu. Apa yang tampak jelas hari ini dapat menjadi teka-teki di kemudian hari. Misalnya, dapatkah Anda dengan mudah menangani kartu berlubang sederhana dari tahun 70-an?

Faktor bus, Burnout, dan binatang fantastis lainnya

Teori itu bagus, tetapi praktik lebih meyakinkan. Berikut ini beberapa contoh, berdasarkan kisah nyata, dengan hanya nama-nama orang dan perusahaan fiktif. Studi kasus singkat ini mencakup masalah paling umum yang muncul akibat praktik dokumentasi teknis yang buruk.

Cerita #1: Ketidakmampuan untuk Berskala

Proyek "NoDocumentationPlease," yang awalnya merupakan perusahaan rintisan streaming video yang sukses, menghadapi masalah serius saat mencoba meningkatkan skala karena dokumentasi teknis yang buruk. Saat tim perlu berkembang, karyawan baru tidak dapat sepenuhnya memahami tugas mereka, dan tidak ada yang dapat memberi mereka penjelasan yang memadai. Tanpa dukungan dan pelatihan yang tepat, karyawan baru dengan cepat pergi. Hal ini tidak hanya memperlambat kemajuan proyek tetapi juga menyebabkan hilangnya bakat-bakat utama, yang pada akhirnya membahayakan efektivitas dan masa depan proyek secara keseluruhan. Akibatnya, para streamer meninggalkan obrolan, dan proyek ditutup.

Cerita #2: Masalah pemeliharaan

Perusahaan "IKnowEverything" mengembangkan platform cloud untuk sinkronisasi dan penyimpanan data. Awalnya, proyek ini berjalan cepat, tetapi seiring berjalannya waktu, para pengembangnya menghadapi kesulitan dalam memelihara dan memperbarui platform karena kurangnya dokumentasi teknis yang jelas dan terkini. Hal ini menyebabkan pengembangan menjadi lebih lambat, lebih banyak bug, dan klien yang tidak puas. Akhirnya, perusahaan mulai kehilangan pelanggan lamanya, dan klien baru memilih pesaing dengan solusi yang lebih stabil dan andal. Pendapatan menurun secara signifikan sementara biaya pemeliharaan yang tidak efektif meningkat. Mendokumentasikan aspek teknis dengan benar sejak awal dapat memungkinkan mereka untuk berkembang dengan sukses. Namun, hal itu tidak dilakukan tepat waktu. Akibatnya, perusahaan tidak dapat mengatasi tantangan teknis dan finansial dan ditutup.

Cerita #3: Kelelahan Pengembang

Proyek "SmartestEver" menghadapi masalah serius karena pengembang utamanya, Andrew, yang menangani hampir semua hal, mengundurkan diri setelah kewalahan dengan banyaknya pertanyaan dari tim. Jika "SmartestEver" memiliki dokumentasi yang tepat, pengembang junior dapat dengan mudah merujuk ke FAQ dan memecahkan masalah rutin. Sebaliknya, mereka membombardir Andrew dengan pertanyaan, dan tanpa dia dan dokumentasi yang diperlukan, tim gagal melanjutkan dan proyek ditutup (tekan F untuk Andrew).

Cerita #4: Faktor Bus

Di perusahaan "NoDocsNeeded," sebuah produk perangkat lunak yang menjanjikan tengah dikembangkan oleh John, seorang pengembang utama, yang memiliki semua pengetahuan tetapi tidak mau repot-repot mendokumentasikannya. Para manajernya pun tidak mau repot-repot membujuknya. Suatu hari, John melakukan perjalanan bisnis dan tidak kembali. Tanpa dokumentasi atau pemahaman tentang arsitektur dan logika produk, anggota tim yang tersisa pada dasarnya tidak dapat berbuat apa-apa. Proyek itu dibekukan, dan uang yang diinvestasikan di dalamnya terbuang sia-sia. Pelajarannya sederhana: dokumentasi dan distribusi pengetahuan dalam sebuah tim sangat penting untuk menghindari ketergantungan pada satu orang. Omong-omong, mereka masih mencari John…

Cerita #5: Tidak ada nabi yang diterima di Open Source

Maria menciptakan pustaka sumber terbuka pertamanya tetapi tidak menulis dokumentasi apa pun untuknya. Tidak seorang pun mengerti apa yang dilakukan pustaka tersebut, dan Maria memutuskan tidak akan menulis pustaka apa pun lagi karena baginya hal itu tidak ada gunanya. Proyek Maria berakhir bahkan sebelum dimulai dan ia memutuskan untuk mengubah profesinya.

Dari anak kabin menjadi kapten

Oke, kita sudah punya teori dan praktik, sekarang mari kita menyelami penelitian dan statistik. Survei Pengembang Stack Overflow 2024 Negara bagian bahwa 84% responden menggunakan dokumentasi teknis untuk memahami fungsionalitas teknologi. Namun, bahkan dengan dokumentasi, mereka sering tidak dapat menemukan jawaban yang mereka butuhkan, seperti yang ditunjukkan oleh sumber daya terpopuler berikutnya: Stack Overflow (80%), Tutorial Tertulis (68%), blog (61%), dan video Cara-cara (54%). Microsoft Research: Kehidupan Sehari-hari Pengembang Perangkat Lunak ditemukan bahwa, rata-rata, pengembang menghabiskan 1-2% dari hari mereka (8-10 menit) untuk dokumentasi, dan 10,3% pengembang mengatakan dokumentasi yang ketinggalan zaman memaksa mereka menghabiskan terlalu banyak waktu untuk mencari jawaban sendiri. Kebutuhan akan dokumentasi juga menjadi perhatian utama bagi komunitas akademis. Pencarian Google Scholar sederhana untuk <"dokumentasi" DAN "perangkat lunak"> hasil panen lebih dari 4 juta hasil, yang secara jelas menunjukkan banyaknya publikasi ilmiah yang membahas masalah tersebut.

Kesimpulan utamanya sangat sederhana: #1 – Setiap orang memerlukan dokumentasi untuk memahami teknologi dan/atau pekerjaan orang lain; tetapi #2 – Hanya sedikit orang yang mau menulis dan memeliharanya; dan akibatnya #3 – Banyak dokumentasi yang ditulis dengan buruk, ketinggalan zaman, dan umumnya tidak berguna. Jadi, apa yang harus dilakukan? Ubah motivasi Anda di semua tingkatan.

Sekelompok peneliti dari Universitas Sains Terapan HAN dan Universitas Groningen (keduanya di Belanda) teridentifikasi Masalah paling umum dengan dokumentasi teknis:

• Dokumentasi informal yang sering digunakan oleh pengembang sulit dipahami;

• Dokumentasi dianggap sebagai pemborosan jika tidak secara langsung memberikan kontribusi terhadap produk akhir;

• Produktivitas pengembang diukur dari jumlah perangkat lunak yang berfungsi saja;

• Dokumentasi sering kali tidak sinkron dengan perangkat lunak sebenarnya;

• Pengembang sering kali hanya berfokus pada jangka pendek, terutama dalam lingkungan pengembangan perangkat lunak berkelanjutan.

  
  

Apakah ada yang terdengar familiar? Saya yakin sebagian besar dari kita pernah mengalami sebagian besar atau bahkan semua masalah tersebut sekaligus dalam pekerjaan rutin sehari-hari. Dan ada hal lain yang lebih dari sekadar penundaan atau kurangnya sumber daya. Beberapa masalah ini berasal dari kurangnya manajemen yang tepat, perencanaan jangka panjang, dan, akhirnya, visi strategis. Dan di sinilah bagian yang sulit, karena bukan hanya kita, para pengembang, yang harus menyelesaikannya. Beberapa masalah harus ditangani oleh para manajer, pemangku kepentingan produk, atau bahkan pemilik perusahaan. Itulah mengapa sangat penting bahwa pandangan yang tepat tentang teknis tidak hanya menjadi pelengkap yang bagus, tetapi bagian dari seluruh nilai inti perusahaan, yang dianut oleh semua orang mulai dari pendiri hingga pengembang junior.