Sebagai pengembang pemula, beginilah cara saya membaca tutorial yang Anda (seorang pengembang) tulis untuk saya

• Tulisan ini menggambarkan secara humoris kebingungan dan hambatan yang dialami pemula saat membaca tutorial teknis yang ditulis oleh para pengembang
• Istilah teknis dan singkatan yang sering digunakan pengembang terdengar seperti “bahasa alien” tanpa konteks bagi pemula
• Langkah instalasi, path file, dan perintah terminal dalam tutorial sering kali terlalu rumit atau ada bagian yang dihilangkan sehingga sulit dipahami
• Penulis menyoroti bahwa penjelasan yang terasa wajar dari sudut pandang pengembang bisa menjadi hambatan yang menuntut berjam-jam pencarian dan trial and error bagi pemula
• Tulisan ini mengingatkan para pengembang yang menulis tutorial bahwa mereka perlu memberi penjelasan yang lebih ramah dan jelas dari sudut pandang pemula

---

Latar belakang tulisan dan persoalan yang diangkat

• Penulis menceritakan pengalamannya sebagai pemula non-pengembang saat membaca tutorial yang ditulis oleh pengembang
• Situasi ketika istilah teknis dan nama alat yang muncul di tutorial sama sekali tidak memberi gambaran apa pun dipaparkan secara satir
• Contoh: nama-nama teknologi fiktif seperti Hoobijag, Snarfus, dan portal Shamrock digunakan untuk menekankan bahwa di mata pemula, semuanya tampak rumit

---

Terjemahan teks asli

“Hai! Saya seorang pengembang. Pengalaman relevan saya seperti ini: saya ngoding dengan Hoobijag dan kadang juga memakai jabbernocks, dan tentu saja saya juga mengerjakan ABCDE++++ (tapi sama sekali bukan ABCDE+/^+, itu kan konyol, ya? Haha!) Dan saya suka bekerja dengan Shoobababoo, serta sesekali menangani kleptomitrons. Saya kemudian mengerjakan kode terkait Shoobaboo di Company[1], dan itu membawa saya ke Snarfus. Nah, mari kita mulai!

Tentang tutorial ini

Awalnya saya mulai melakukan sesuatu yang sangat sederhana[2] dengan Snarfus, dan makin saya pakai, makin saya melihat potensinya! chromus memang agak berantakan, tapi sebenarnya sangat serbaguna. Jadi saya mulai melakukan argyling pada pintafore dengan quagmire alih-alih hoobastank! Gila, saya tahu. Tapi sampai titik tertentu itu berhasil, dan sebenarnya cukup menyenangkan… sampai saya menemui hambatan besar: fisterfunk sama sekali tidak mau berkomunikasi dengan portal shamrock, juga tidak mengirim beep-boops ke Snarfus! Tentu saja Anda tahu apa artinya itu[3]— sekarang seluruh hoob-tunnel tersumbat oleh gramelions. Tidak bisa diterima.

Saya hampir menyerah, tapi lalu saya sadar: kalau backside Snarfus stagnator disambungkan ke backside shamrock Klingon troglodyte emulater, semuanya akan baik-baik saja! Semuanya mulai beep-boops dan ding-dongs, dan akhirnya saya bisa sampai ke topik utama tutorial ini. Dan saya pun bisa melakukan sesuatu yang sangat sederhana dengan cara yang saya inginkan! Cukup keren, kan[4].

Jadi begini cara menyiapkannya:

1. Di terminal, masukkan ajkl;gawgor;iqeg;iJLkqen. wl;R aw;oeiga 4648664 arjarwgj;llj;ja fadgfgajkljl; wlj;sdjk;lfas
2. Sekarang buka folder/hidden/deep/in/the/file/system/surprise!.file dan salin isi filenya. Kalau tidak ada di sana, mungkin ada di library/library/library/llibrary/liiiiiibrarrrary/llllliiiiibrary/hidden/hidden/hiding/you can’t find me/hidden/nope/never/hahahahereiam.file
3. Kembali ke terminal, tempel isi file itu, lalu masukkan 64A786AGR45JAR; rdja;jg [[]][[]][[]][[]]][()()()()()()()(){{}{}{}|{}{|}{}{|}{ ////////////////!! !!!! !! //// !!! agjlkargji;lwej;OI [ASRGASG[]ASGDASG[]EAEadgasg[]EAGE[edaga][]ahgr-0-0=-0-=0-=0=0-0=-0-=0=-0-=0=-0=-0!!!
4. Boop![5]
5. Buka Snarfus dan unggah file yang baru saja Anda buat
6. Hanya untuk iseng, kalau Anda ingin melepaskan sham dari chronostatiomatrix —()()(]]asdg a=-do —cd go cd stay —sususudododo baby shark—][] juga bisa dijalankan. Ini opsional
7. Selesai!

Beri tahu saya hasilnya. Saya juga penasaran apakah ada yang memakai metode ini bersama GewGawGamma atau ometer2.7.”

---

Penjelasan catatan kaki

1. Sepertinya perusahaan terkenal, tapi saya tidak tahu
2. Sama sekali tidak sederhana
3. Saya tidak tahu artinya apa
4. Memang keren, tapi saya tetap tidak paham. Meski begitu, saya ikut senang Anda bisa melakukannya
5. Tiga langkah pertama kemungkinan akan membutuhkan sekitar 7 jam dan 193 kali pencarian. Tapi saat berhasil sampai ke Boop!, rasanya sangat memuaskan

Penutup

• “Ini cuma tulisan untuk lucu-lucuan. Saya sungguh berterima kasih kepada semua orang yang berbagi pengetahuan dan menulis tutorial.”

[GN⁺]

Komentar Hacker News

• Saya sangat merekomendasikan pendekatan menyuruh seseorang yang hanya punya pengetahuan minimum untuk mengikuti dokumentasi, lalu mengawasinya diam-diam dari samping. Pada saat itu jangan membantu sama sekali, cukup amati. Dalam prosesnya, Anda bisa menemukan berbagai masalah seperti di mana pengguna tersendat, bagian yang bagi penulis sudah terlalu familier sehingga tak terpikir lagi, atau pengaturan yang terlewat. Jika pengguna bisa mencapai tujuannya tanpa banyak stres, berarti dokumentasinya lolos. Jika tidak, semua titik kegagalan harus dicatat tanpa ada yang terlewat, lalu masing-masing diperbaiki dan diuji lagi dengan orang baru. Saya bahkan pernah memakai dokumentasi perusahaan besar seperti FAANG yang tidak lolos standar ini. Saya sangat bersyukur organisasi kami menetapkan standar yang tinggi. Jika dokumentasi dibuat dengan cara seperti ini, rapat berulang, permintaan dukungan, dan panggilan video akan berkurang, dan pengguna jadi bisa menyelesaikan masalah sendiri

  • Saya sering mengalami masalah seperti ini saat memakai dokumentasi Apple. Definisi di dalam dokumentasinya sering cuma mengulang nama istilah tanpa penjelasan, padahal seharusnya ditulis lebih konkret
  • Aturan “jangan bicara, hanya amati” kelihatannya mudah, tetapi kenyataannya banyak orang tidak tahan lalu ikut menjelaskan atau memberi petunjuk. Bahkan ada yang sampai langsung memegang mouse. Untuk menghindari reaksi manusiawi seperti ini, akan membantu jika ada moderator netral tersendiri dan penulis/pengembang hanya mengamati. Namun, penting untuk mempelajari keterampilan “sekadar mengawasi”, dan jika ingin lebih berkembang saya sarankan mempelajari "think-aloud protocol" (protokol berpikir keras)
  • Sebagian besar dokumentasi onboarding tim perusahaan kualitasnya sangat buruk, sampai-sampai menjadi jendela awal yang memperlihatkan beban kerja nyata. Tiga tim terakhir yang saya masuki hampir tidak punya dokumentasi atau dokumentasinya sudah usang, jadi saya harus mencari orang yang relevan satu per satu untuk mendapatkan akses yang dibutuhkan atau informasi pipeline deployment, lalu selama proses itu saya menulis dokumentasi baru, tetapi begitu ada sistem atau izin tambahan, dokumentasinya langsung usang lagi. Hanya ada satu tim yang menyiapkan seluruh lingkungan yang saya butuhkan dalam dua hari, dan itu pengalaman terbaik. Sekarang saya berada di tim devex baru dan sedang berusaha memperbaiki lingkungan dokumentasi itu sendiri
  • Onboarding sambil membaca dokumentasi setup yang buruk rasanya benar-benar 10 kali lebih menegangkan. Saya selalu mendorong agar masalah yang dialami karyawan baru langsung diperbaiki sebagai kontribusi pertama mereka. Orang baru tidak punya konteks sama sekali, jadi mereka bisa menjadi reviewer terbaik
  • Organisasi kami juga memakai alur kerja yang sama. Kami menyuruh orang yang kurang berpengalaman mengikuti dokumentasi, lalu mendorong semua orang untuk terus memperbaikinya. Sebagai orang yang sudah lama berpengalaman, pemula bisa menangkap “blind spot” yang muncul dengan sangat baik. Dari pengalaman saya, saya juga belajar bahwa mengelola kepercayaan diri pengguna itu sangat penting. Karena itu, saat memandu langkah seperti “jalankan perintah shell ini”, kami secara default menyediakan beberapa bagian yang bisa dilipat (misalnya contoh output yang berhasil, peringatan yang bisa diabaikan, daftar error yang mungkin muncul dan cara menanganinya, penjelasan perintah yang rumit, dan sebagainya). Beberapa langkah bahkan disertai penjelasan sepanjang satu halaman, tetapi detail seperti ini ternyata sangat membantu saat onboarding

• Judul blog post aslinya adalah “Sebagai non-developer, saya membaca tutorial yang Anda, seorang developer, tulis”, tetapi judul HN diubah menjadi “Sebagai developer pemula...”. Non-developer dan developer pemula adalah dua hal yang sama sekali berbeda. Misalnya, bagi tim HR atau orang yang benar-benar bukan dari bidang ini, istilah internal atau konsep dasar bisa sama sekali asing. Dalam kasus seperti itu, jika developer menulis penjelasan yang benar-benar meleset, wajar jika dikritik. Sebaliknya, developer pemula meskipun kesulitan tetap bisa mencari istilah atau konsep baru sendiri, dan setelah beberapa waktu bahkan bisa memperbarui dokumentasi untuk pemula berikutnya

  • Sebagai catatan, saya mengirimkannya dengan judul “non-developer”, tetapi di tengah jalan diubah menjadi “developer pemula”. Penulisnya adalah blogger non-teknis, dan untuk mengelola website atau CSS, ia pasti harus merujuk ke berbagai dokumen teknis. Saya rasa mungkin lebih tepat membahas publikasi situs dan ketiadaan dokumentasi untuk non-spesialis, tetapi tidak apa-apa juga jika komunitas HN membawa diskusinya ke arah lain
  • Perbedaan ini sangat penting. Penulis Annie mengatakan bahwa dirinya bekerja di bidang “konten/dokumentasi” dan juga punya hobi CSS, jadi ia berada di lapisan “developer hobi non-profesional”. Menurut saya ini akan menjadi area yang makin besar. Saat menulis tutorial yang juga mencakup pemula/non-developer, cukup tambahkan keterangan sangat singkat pada frasa seperti cd ~/.snarfus (buat foldernya jika belum ada) pun sudah cukup. Saya sendiri saat dulu memasang Debian sangat terbantu hanya oleh satu penjelasan kecil seperti itu
  • Situs yang paling mengesankan saya saat mulai belajar pemrograman adalah “FromZero”. Situs itu menjelaskan langkah demi langkah mulai dari memasang IDE sampai membuka konsol untuk non-developer, dan menenangkan pembaca dengan gaya seperti “ini akan dibahas nanti, jadi untuk sekarang jangan khawatir”. Itu sangat bagus. Tentu saja, menulis dokumentasi butuh banyak waktu dan usaha, jadi kadang dokumentasi dengan penjelasan parsial pun lebih baik daripada tidak ada sama sekali. Menurut saya, dokumentasi untuk developer pemula seharusnya ditulis dengan perhatian setingkat dokumentasi untuk non-developer
  • Saya merasa ada orang yang menganggap kalau sesuatu tidak dijelaskan dengan sangat mudah maka itu gatekeeping, dan mereka mengabaikan fakta bahwa meskipun terasa sulit, tidak mungkin memahami apa pun secara instan tanpa pengetahuan awal
  • Jika ini tutorial untuk developer pemula, bukan tulisan yang ditujukan kepada developer profesional, maka aneh jika mengharapkan semua konsep seperti “Hoobijag” atau “shamrock portal” dijelaskan satu per satu. Faktanya, kita semua dulu belajar sambil mencari istilah yang belum kita tahu di Google

• Kebanyakan tutorial sebenarnya bukan untuk non-developer, melainkan lebih mirip pertukaran informasi antarsesama developer, posisinya serupa dengan makalah akademik yang ditujukan kepada kelompok berpengetahuan tertentu. Cara seperti ini juga tidak buruk. Bahkan dokumentasi yang saya tulis untuk catatan masa lalu saya sendiri jadi mudah dicari kembali. Itulah sebabnya ada kursus atau materi terpisah untuk pemula. Jika setiap tutorial harus selalu dimulai dari seluruh penjelasan latar belakang sepanjang 30 ribu kata, tidak ada yang akan membacanya sampai selesai. Sebaliknya, sekalipun ditambah lebih banyak penjelasan latar belakang, bagi seseorang itu tetap bisa terasa belum cukup

  • Anak saya (17 tahun) sangat tertarik pada pemrograman, dan baru-baru ini saya menjelaskan konsep public/private/internal/static plus rekursi kepadanya. Saya diam-diam menunggu seperti apa reaksinya nanti
  • Saya tidak setuju dengan klaim bahwa “kebanyakan tutorial bukan untuk non-developer”. Saya ingin menegaskan bahwa judul tutorial kali ini sendiri jelas dimaksudkan untuk non-developer. Saat kesulitan memasang proyek open source, suara yang menuntut agar bahkan panduan instalasi paling dasar dibuat cukup mudah supaya pemula bisa mengikutinya memang sangat dibutuhkan. Jika langkah sepele saja terlewat, di bidang yang tidak familier seseorang bisa membuang waktu berjam-jam
  • Saya juga tidak melihat ada salahnya menulis dokumentasi yang lebih ramah untuk semua orang. Dokumentasi yang bagus berguna bukan hanya bagi pemula, tetapi juga bagi developer. Alasan tidak adanya dokumentasi yang mudah diakses hanyalah karena orang tidak mau mengeluarkan sedikit usaha tambahan. Lagi pula, tidak seperti makalah, dokumentasi developer sering bermasalah karena ditulis terlalu ringkas atau penulisnya tidak memikirkan pembaca. Akibatnya, dokumen itu akhirnya hanya berguna bagi para ahli. Itu adalah kegagalan
  • Saya setuju bahwa diperlukan dokumentasi yang membangun konteks untuk pemula langkah demi langkah. Hanya saja, belakangan ini DX (developer experience) sering ditingkatkan hanya dari sudut “yang mudah”, sambil mengorbankan log atau kemampuan pencarian pesan error yang dulunya berguna, sehingga malah hanya membidik pemula dan membuat pengguna lama jadi tidak nyaman
  • Tutorial masa kini tampaknya sering sebenarnya adalah tulisan untuk mengelola rekam jejak “saya berkontribusi pada proyek X”. Justru akan menjadi perbaikan besar jika penulis mencoba lagi mengikuti tutorialnya sendiri tiga bulan kemudian; isi yang hilang akan langsung terlihat jelas

• Banyak technical writer tidak benar-benar menyadari “kutukan pengetahuan”. Dulu saya pernah menjalankan guild WoW (World of Warcraft). Empat puluh orang berkumpul bersamaan untuk masuk ke dungeon dan bekerja sama menghadapi beberapa boss, dan satu kesalahan kecil saja bisa membuat seluruh tim wipe. Karena itu, semua orang berkumpul di Teamspeak dan strategi dijelaskan dengan sangat cukup sebelumnya. Pelajaran terbesar saat itu adalah “anggap lawan bicara tidak tahu apa yang sedang saya katakan” dan “hal yang sudah dikatakan pun harus diulang”. Kebanyakan orang tidak akan menyela untuk bertanya meskipun ada yang tidak mereka pahami, jadi kebiasaan terus bertanya pada diri sendiri “istilah apa yang sedang saya pakai?” dan “apakah mereka mungkin tidak tahu konsep ini?” lalu menambahkan penjelasan ternyata sangat efektif. Pengalaman komunikasi seperti ini berlaku persis sama dalam technical communication juga, dan jika Anda membiasakan diri berusaha melampaui “kutukan pengetahuan”, Anda bisa meningkatkan pemahaman orang lain

  • Dulu di guild raid saya pernah melihat seorang guild master berusia 18 tahun mengumpulkan orang dewasa dari berbagai zona waktu lalu mengatur pembagian loot, strategi, dan jadwal dengan sangat lancar, dan saya berpikir, “anak ini seharusnya langsung direkrut jadi manajer”
  • Siapa pun yang punya pengalaman menjalankan raid 40 orang akan memiliki kemampuan tingkat atas sebagai project manager. Itu benar-benar seperti memimpin “sekawanan kucing liar” dengan rapi

• Banyak homepage proyek atau README GitHub ditulis dengan sikap seolah-olah “orang yang membaca ini sudah tahu semuanya”. Saat saya melihat dokumentasi, saya ingin ada perhatian lebih pada hal-hal seperti “mengapa alat ini diperlukan”, “masalah apa yang diselesaikannya”, “apa bedanya dengan alat lain yang mirip”, “apakah masih terus dipakai sekarang”, dan “apakah pembaca diberi bahan yang cukup agar bisa menilai sendiri kelebihan dan kekurangannya”. Hanya dengan meluangkan 5 menit untuk memikirkan “bahkan pemula sekalipun akan penasaran tentang apa?” lalu menuliskannya, aksesibilitas akan meningkat drastis. Sangat disayangkan bila proyek yang dibuat selama bertahun-tahun akhirnya berulang kali membuat pengguna menyerah karena merasa repot bahkan sebelum sadar mereka sebenarnya sudah menemukannya. Dan penting juga memahami peran tiap jenis dokumentasi dengan baik. https://diataxis.fr/ adalah titik awal yang bagus

  • Di bidang ROS (robot software), saya selalu stres karena README benar-benar minim. Selain nama proyek, sering tidak ada petunjuk apa pun, sampai-sampai memahami kegunaannya saja sulit. Ini bukan cuma masalah open source; saya mengalami hal yang sama di tempat kerja, dan rasanya saya satu-satunya orang yang mau menambahkan penjelasan ke README. Masa monorepo dulu justru terasa lebih membahagiakan
  • Saya paham ini adalah alat yang dibuat developer dengan cinta dan kerja keras, tetapi kalau dokumentasinya saja dijaga dengan baik, hambatan masuknya akan jauh lebih rendah. Ditambah lagi, jika dokumentasi komponen lain yang membentuk stack juga sulit dipahami, learning curve-nya akan menjadi jauh lebih curam secara eksponensial
  • Dulu bahkan pernah ada proyek yang naik ke HN tanpa menuliskan “ini sebenarnya apa”

• Hal terpenting saat menulis dokumentasi adalah menetapkan dengan jelas ‘tingkat pengetahuan pembaca sasaran’. Tidak masalah apakah patokannya dibuat tinggi atau rendah, tetapi jika terlalu menyimpang dari baseline itu, sebagian pembaca pasti akan merasa tidak puas. Dalam situasi seperti ini, Anda bisa memilih beralasan atau mencari solusi. Faktanya, dengan AI, Google, buku, dan sebagainya, sekarang apa pun bisa segera dicari. Jika penasaran “apa itu Shoobababoo” atau “mengapa memakai quagmire”, Anda tinggal mencarinya. Tentu idealnya dokumentasi ditulis semandiri mungkin tanpa perlu informasi eksternal, tetapi dunia tidak selalu memberi kebaikan sebesar itu

  • Itulah mengapa kecenderungan banyak panduan setup yang dimulai dari “sekarang klik dua kali file exe lalu next terus” justru lebih bermasalah. Menetapkan baseline panduan memang sangat penting
  • Saya terutama menulis dokumentasi untuk sistem internal yang sensitif, dan kadang di bagian paling depan saya menuliskan dengan jelas, “panduan ini mengasumsikan Anda sudah tahu cara menggunakan x, y, z. Jika tidak, Anda tidak boleh melakukan pekerjaan ini.” Aksesnya memang dibatasi, tetapi untuk berjaga-jaga jika seseorang yang tidak familier harus memakainya, misalnya dalam skenario DR, saya sengaja meninggalkan batas seperti “kalau Anda bahkan tidak paham ini, jangan pernah lakukan”

• Prinsip yang sudah lama saya tekankan selama mentoring adalah “hal terbaik yang bisa dilakukan dengan pengetahuan adalah membagikannya”. Jika Anda tahu sesuatu, jelaskanlah. Kalau ternyata orang yang Anda beri tahu sudah tahu, paling-paling Anda hanya menambah keyakinannya; kalau belum tahu, itu akan sangat membantu. Kadang ada keluhan bahwa saya terlalu bertele-tele, tetapi jika saya bilang “ini ditulis untuk berjaga-jaga kalau ada karyawan baru, pelanggan, atau manajer yang membacanya”, kebanyakan orang mengerti. Prinsip ini berlaku di semua bidang, termasuk development, reporting, dan people management

  • Tentu saja, ada juga orang yang sangat tidak suka dijelaskan hal yang sebenarnya sudah mereka ketahui. Jika rasio signal-to-noise terlalu buruk, komunikasi malah bisa terhambat
  • Pengalaman saya mengajari anak bermain biliar juga serupa. Budaya membuang sikap defensif dan tidak pelit membagikan tip antarrekan sangat membantu pertumbuhan. Dalam mentoring, jika alih-alih memberi jawaban kita membimbing lewat pertanyaan agar mereka menemukan sendiri, perkembangan sejati terjadi saat mereka menyadarinya sendiri
  • Memberi tahu semua orang satu per satu bisa disalahartikan sebagai “mansplaining” atau dianggap “berlagak tahu segalanya”, dan secara politik bisa terasa mengancam. Di perusahaan, kadang justru lebih aman jika kita hanya menjawab saat orang lain bertanya

• Baru-baru ini saya mencoba men-deploy aplikasi ke DigitalOcean Kubernetes lewat Gitlab, dan saya harus mengimplementasikan 3–4 alat pihak ketiga tanpa penjelasan alat itu melakukan apa, serta harus mengisi sendiri nama atau path yang harus dimasukkan ke command line. Tidak ada penjelasan apa yang menjadi acuan dan apa yang harus dicocokkan. Meskipun kemampuan Docker saya cukup baik, dokumentasi alat-alat ini terasa begitu tidak ramah sampai rasanya lebih baik tidak ada dokumentasinya sekalian

• Alasan utama saya berhenti menulis buku dan membuat website tutorial adalah karena tutorial bisa dibuat lebih mudah diakses oleh lebih banyak orang dengan bantuan berbagai alat interaktif (seperti elemen <abbr> dan sebagainya). Meskipun begitu, saya tetap frustrasi karena konten web saat ini masih berhenti pada fungsi buku kertas. Ada begitu banyak fitur seperti klik, hover, melipat area, video, respons pengguna, dan lain-lain, tetapi yang masih melimpah justru teks panjang seperti dinding. Bahkan OP pun memakai cara yang saat catatan kaki diklik lalu halaman bergulir ke bagian paling bawah, dan itu terasa seperti belum benar-benar memanfaatkan potensi web

  • Saya sedang mencoba meng-upgrade blog saya sekarang; kalau ada yang bisa merekomendasikan situs yang bagus dalam hal ini (tutorial interaktif yang dibuat dengan baik), saya akan sangat berterima kasih

• Sebenarnya sebagian besar tutorial sering kali bukan untuk non-developer maupun developer, melainkan sekadar ‘teks panjang yang tidak perlu’ yang pada akhirnya tetap melewatkan satu atau dua langkah penting. Menurut saya penyebab terbesarnya adalah sulitnya menulis seolah-olah sedang menjelaskan kepada orang lain. Jika isi yang hanya ada di kepala penulis tidak benar-benar dituangkan ke dalam tulisan, pembaca tidak akan pernah tahu. Daripada gaya ‘tutorial’, sebaiknya ditulis seperti ‘cookbook’ agar lebih berguna di praktik nyata dan tidak cepat usang setelah ada pembaruan versi

  • Ironisnya, resep online (cookbook) masa kini justru sering berisi omong kosong yang jauh lebih tidak perlu dibanding blog non-developer