Contoh adalah dokumentasi terbaik

 (rakhim.exotext.com)
38 poin oleh GN⁺ 2025-10-11 | 8 komentar | Bagikan ke WhatsApp
  • Saat developer mencari dokumentasi, 95% kasus cukup diselesaikan dengan contoh sederhana saja, tetapi kasus ketika contoh bisa ditemukan di sumber resmi hanya sekitar 5%
  • Dokumentasi teknis resmi pada dasarnya ditulis untuk orang yang sudah sangat mendalami ekosistem terkait, sehingga bagi developer yang berpindah-pindah antarproyek dan bahasa, dibutuhkan energi mental yang besar untuk memulihkan konteks
  • Jika melihat dokumentasi fungsi max() di Python, ada banyak pengetahuan prasyarat yang diperlukan untuk memahami sintaks definisi fungsi dan konsep-konsepnya, padahal dengan 5 baris contoh sederhana, fungsi itu bisa langsung dipahami
  • clojuredocs.org milik komunitas Clojure menyediakan dokumentasi praktis melalui contoh yang dikontribusikan pengguna, dan menjadi praktik terbaik yang meningkatkan kegunaan nyata dengan menyertakan fungsi-fungsi terkait
  • Bahkan proyek perangkat lunak besar pun jarang menyediakan 4 jenis dokumentasi, sehingga developer akhirnya mencari tutorial, bukan karena butuh panduan, melainkan karena mereka membutuhkan contoh

Pentingnya contoh saat mencari dokumentasi

  • Saat developer mencari dokumentasi, dalam 95% kasus satu contoh saja sudah cukup
  • Namun, kasus ketika contoh bisa ditemukan di sumber resmi hanya sekitar 5%
  • Sebagian besar dokumentasi teknis resmi ditulis terutama untuk orang yang sudah sangat mendalami ekosistemnya
  • Banyak developer sehari-hari harus men-juggling beberapa "dunia" di dalam kepala mereka
    • Perpindahan antarproyek, bahasa, dan framework terjadi sangat sering
    • Mengembalikan konteks dan memahami situasi menghabiskan energi mental yang besar

Analisis kasus dokumentasi Python

  • Contoh fungsi max() di dokumentasi Python 3
    • max(iterable, /, *, key=None): mengembalikan item terbesar
    • Setelah itu penjelasan berlanjut dalam 5 paragraf pendek
  • Pengetahuan Python yang harus diketahui untuk memahami dokumentasi ini
    • Arti * dalam definisi fungsi
    • Arti / dalam definisi fungsi
    • Konsep "positional-only parameter separator"
    • Konsep iterable
    • Konsep keyword-only arguments
    • Makna umum parameter key
  • Kita harus membaca teksnya untuk memahami nilai seperti apa yang harus diberikan dan bagaimana benar-benar memanggil fungsi tersebut

Efek dari contoh sederhana

  • Diakui bahwa detail penting tidak selalu bisa dihilangkan demi keringkasan
  • Namun, banyak developer datang ke halaman tersebut hanya untuk cepat menemukan cara memberikan fungsi pengurutan kustom (key) ke fungsi max
  • Jika ada contoh seperti di bawah ini, mereka bisa langsung mendapatkan informasi yang dicari 
    max(4, 6) # → 6  
max([1, 2, 3]) # → 3  
max(['x', 'y', 'abc'], key=len) # → 'abc'  
max([]) # ValueError: max() arg is an empty sequence  
max([], default=5) # → 5
  • Melalui contoh, hal itu bisa dipahami dengan mudah dan intuitif

Praktik terbaik dari komunitas Clojure

  • clojuredocs.org adalah proyek berbasis komunitas Clojure
    • Pengguna berkontribusi contoh untuk fungsi-fungsi bawaan
    • Menjadi sumber daya yang tak tergantikan dalam kegiatan coding sehari-hari
  • Contoh halaman: lihat into, spit, map
  • Ciri-ciri contohnya
    • Tidak hanya fungsi tersebut, tetapi juga fungsi-fungsi terkait ikut disertakan
    • Meningkatkan kegunaan nyata dan kepraktisan

Keterbatasan dokumentasi saat ini

  • Bahkan proyek perangkat lunak besar pun jarang menyediakan 4 jenis dokumentasi
  • Alasan orang ragu mengklik tautan "Documentation"
    • Kebanyakan berupa referensi API yang dihasilkan otomatis, ringkas, dan sulit dibaca
  • Alasan sebenarnya developer mencari tutorial
    • Bukan karena mereka butuh panduan, tetapi karena mereka membutuhkan contoh
    • Tutorial lebih berguna karena memang menyertakan contoh

Bacaan terkait

8 komentar

 
sonnet 2025-10-12

Sejujurnya, saya rasa ini terutama berlaku untuk Java dan Python. Ekosistemnya juga cenderung kuat dengan chauvinisme bahasa masing-masing atau budaya yang terisolasi secara paradigma.
Kalau memakai Python sebagai acuan, isinya memang cukup pas, tetapi ketika mempelajari berbagai bahasa, bagian 5% itu terasa cukup berlebihan.
 
kuber 2025-10-12

Contoh adalah dokumentasi terbaik

Datanglah ke Golang, tempat kode adalah dokumentasi~
Kami mengembangkan dengan membedah kode uji bahkan tanpa README
 
pjtco 2025-10-11

Saya kira cuma saya yang kurang pintar sampai tidak bisa paham dokumentasi resmi wkwk
Kalau benar-benar dikasih contoh lalu dijelasin sedikit saja, langsung cepat paham.....
 
nemorize 2025-10-11

PHP mungkin akan menjadi contoh yang bagus sekaligus contoh yang terburuk.

Di satu sisi, ini menjadi contoh yang baik karena di dokumentasi resmi pengguna bisa mengunggah konten kontribusi sehingga kita bisa melihat berbagai contoh kode.

...di sisi lain, PHP punya banyak perbedaan BC yang subtil pada fungsi-fungsi bawaannya, dan contoh-contoh kontribusi itu kebanyakan berasal dari versi zaman baheula, jadi tercampur dengan hal-hal yang sedikit berbeda dari perilaku sebenarnya dan malah menambah kebingungan... wkwk..k...
 
savvykang 2025-10-11

Kalau melihat dokumentasi pengembangan iOS atau Cocoa zaman dulu, ada bagian use case tersendiri; bukankah itu metode dokumentasi yang tepat? Contoh, signature fungsi, dan penjelasan perilaku semuanya diperlukan
 
aer0700 2025-10-11

Dulu kekurangan dokumentasi resmi tertutupi oleh Stack Overflow dan pencarian Google, sedangkan sekarang rasanya kekosongan itu diisi oleh LLM.
 
GN⁺ 2025-10-11
Komentar Hacker News

  • Hal terbaik dari Python lama adalah saat membuka dokumentasi library, ada bagian yang merangkum argumen fungsi dan nilai kembaliannya dengan jelas. Belakangan ini, banyak dokumentasi library JavaScript atau Python yang hanya menyediakan contoh, dan itu cukup disayangkan. Untuk membuat sesuatu dengan cepat, contoh memang bagus, tetapi untuk memperbaiki masalah atau mempelajari library, penjelasan nilai argumen itu sangat penting. Tidak masalah kalau contoh menjadi bonus, tetapi itu tidak boleh jadi satu-satunya isi dokumentasi

    • Sebenarnya yang Anda inginkan adalah definisi tipe. Definisi tipe berfungsi sebagai dokumentasi yang baik. Alat sistem tipe sudah menampilkan banyak informasi langsung di editor atau IDE, jadi kebutuhan untuk membuka dan membaca dokumentasi secara manual jadi berkurang. Meningkatnya dokumentasi yang berpusat pada contoh akhir-akhir ini terjadi karena perubahan alur kerja tersebut. Ada anggapan bahwa tidak perlu lagi menulis ulang di dokumentasi hal-hal yang sudah diberikan oleh alat tipe. Saat melihat dokumentasi, saya lebih tertarik pada “masalah apa yang bisa diselesaikan alat ini” daripada detail argumennya. Contoh sangat unggul dalam menunjukkan kemungkinan itu. Saat ingin menyelesaikan masalah tertentu, melihat contoh memungkinkan kita cepat menilai apakah alat tersebut akan membantu. --- Jika ada sistem tipe, saya ingin melihat contoh terlebih dahulu. Jika tidak ada sistem tipe, 1) saya tidak puas. 2) saya tetap ingin melihat contoh dulu, lalu penjelasan detail tentang argumen/pengembalian/struktur data

    • Dokumentasi yang baik membutuhkan keduanya. Jelaskan dulu detailnya, lalu tambahkan berbagai contoh agar pembaca bisa memeriksa pemahamannya. Kadang contoh saja cukup, tetapi jika kombinasi opsinya terlalu banyak, hampir mustahil menampilkan semuanya lewat contoh. Karena itu, penjelasan untuk tiap opsi perlu diberikan lebih dulu, lalu siapkan contoh untuk sebanyak mungkin kasus agar pembaca bisa mengembangkannya sendiri. Dan dokumentasi yang baik sangat sulit dibuat, serta akhir-akhir ini benar-benar jarang terlihat

    • Saya tidak sepenuhnya setuju. Dokumentasi bergaya Javadoc adalah dokumentasi pemrograman yang berbasis tipe dan docstring inline. Itu memang wajib ada, tetapi tidak harus dibuka lewat web; melihat langsung kodenya lebih efisien. Panduan seperti contoh atau QuickStart juga wajib ada. Itu menurunkan hambatan masuk ke library. Hanya dengan melihat kode, cara memakai API tidak mudah dipahami. Dulu banyak library Java yang hanya menyediakan Javadoc, dan saya pernah kesulitan karena tidak tahu cara memakainya

    • Menurut saya, contoh yang diberi komentar dengan baik adalah yang terbaik. Namun itu tidak bisa menggantikan dokumentasi tradisional

    • Saya penasaran apakah Anda pernah mempertimbangkan bahwa gaya belajar orang lain bisa berbeda dari Anda. Saya tidak paham kenapa ada resistensi terhadap gagasan bahwa contoh harus menjadi bagian dari dokumentasi. Contoh mengurangi gesekan saat berpindah konteks dalam berbagai situasi

  • Halaman man Unix juga sangat membutuhkan contoh. Biasanya halaman itu hanya berfungsi sebagai referensi untuk orang yang sudah sangat paham alatnya, jadi sama sekali tidak membantu pemula. Dokumentasi yang baik membutuhkan keduanya

    • Sangat setuju. Saya ingin mengingatkan semua penulis halaman man bahwa ada bagian konvensional bernama EXAMPLE. Lihat dokumen resmi man(1)

    • Saya pribadi belum pernah merasakan masalah seperti itu. Saya biasanya mulai dengan membuat kodenya sambil mempelajari perintah atau istilah, lalu melihat satu per satu kode error yang dikembalikan beserta penyebabnya, juga arti parameternya. Tanpa contoh pun, dokumentasi yang lengkap sudah cukup. Sebaliknya, hanya memberi contoh tanpa penjelasan itu benar-benar yang paling buruk. Dokumentasi macam apa yang bahkan tidak menjelaskan apa parameternya dan apa artinya?

    • Menarik bahwa Stack Overflow dulu juga pernah mencoba hal serupa. Mereka mengoperasikan Stack Overflow Documentation dalam versi beta dari 2016 hingga 2017. Tujuannya membuat dokumentasi yang berpusat pada contoh, tetapi akhirnya dihentikan. Meski begitu, konten yang ditinggalkan komunitas masih tersedia secara publik dengan lisensi CC BY-SA

    • Coba lihat cheat.sh. Saya memakainya langsung dari skrip dengan curl cheat.sh/"$1"

    • Saya selalu terkejut mengetahui bahwa ternyata cukup banyak halaman man yang memang punya contoh. Meski begitu, masih ada banyak ruang untuk perbaikan yang lebih menyeluruh

  • Contoh bukan hanya bagus untuk pemula atau pengguna sesekali. Pengguna mahir juga membutuhkan dokumentasi formal, yaitu dokumentasi yang mencakup semua konfigurasi parameter. Misalnya, dokumentasi requests selalu membuat Google mengarahkan saya ke halaman penuh contoh seperti Quickstart, dan itu menyulitkan. Semua orang tahu HTTP GET, tetapi sulit mencari opsi lain, bagaimana menangani timeout, atau apakah raise_for_status mengabaikan 204. Keduanya memang diperlukan, tetapi jika waktu developer terbatas, saya akan memilih menyediakan dokumentasi yang benar terlebih dahulu. tautan contoh requests Quickstart

    • Dengan melihat contoh, perilaku jauh lebih mudah dipahami dibanding dokumentasi bergaya referensi. Orang-orang lemah dalam segala hal mulai dari memberi nama, menyusun konsep, sampai menulis dokumentasi. Baru-baru ini saya juga menghabiskan beberapa jam karena satu parameter hanya bekerja dalam kondisi tertentu. Kodenya terlalu rumit untuk ditelusuri, dan bahkan LLM salah mengatakan bahwa parameternya tidak terdokumentasi. Pada akhirnya, cara paling efisien adalah membuat kode contoh sampai saya menemukan perilaku yang diinginkan. Contoh dapat merangkum banyak hal penting sekaligus dan memungkinkannya diverifikasi dengan cepat. Sebaliknya, dokumentasi API mencoba membahas semuanya sehingga sulit dirawat dan gagal menyampaikan intinya. Dan kecuali benar-benar jelas, saya tidak pernah mempercayai perilaku library. Jika tidak ditunjukkan dengan jelas di README atau ditentukan lewat tipe, saya selalu menganggap perilaku itu bisa berubah kapan saja. Akhirnya saya menulis kode pemanggil sebersifat defensif mungkin

    • Contoh penting bukan hanya untuk pemula, tetapi untuk semua orang. Contoh 5 detik bisa memberi efisiensi setara satu jam membaca dokumentasi dan bereksperimen. Beberapa dokumentasi git seperti itu, dan hal yang sama berlaku untuk fungsi yang pada dasarnya sederhana tetapi sulit dijelaskan. Bahkan jika developer hanya bisa membuat satu hal, mereka tetap cukup mampu mengeluarkan contoh sekaligus dokumentasi. Keduanya harus disediakan, kecuali dalam kasus yang benar-benar sangat jelas

    • Setuju. Dokumentasi yang baik hampir harus mendefinisikan dengan jelas keseluruhan perilaku program, dan sulit melakukan itu hanya dengan contoh

    • Kita bisa punya keduanya sekaligus. Contoh dan dokumentasi teknis bukan hal yang saling meniadakan

    • pembicaraan tentang occasional users itu persis maksud saya. Setiap kali berpindah antarproyek, bahasa, atau framework, ada biaya mental yang besar untuk memulihkan konteks dan memahami situasinya

  • Orang mungkin punya banyak komentar soal Perl, tetapi dokumentasi Perl benar-benar membantu. Selalu ada bagian SYNOPSIS di depan, jadi langsung ada contoh kode yang bisa dipakai. Setelah itu baru penjelasan, referensi, dan contoh tambahan. Contoh: dokumentasi bigrat, dokumentasi Archive::Tar. Saat menulis dokumentasi proyek, gaya Perl layak dijadikan acuan. Dan gaya itu sendiri juga didokumentasikan dengan baik

    • Saya memakai Perl di awal 2000-an lalu tanpa sengaja memakainya lagi pada 2014, dan rasanya seperti semuanya langsung teringat kembali. Mungkin karena sudut pandang linguistik dan sikap Larry Wall, kesannya jadi sangat membekas. Bukan karena presisi matematis, tetapi lebih karena terasa seperti “berbicara dengan seorang teman”

  • Keduanya diperlukan. Contoh memberi gambaran cepat, memudahkan integrasi, dan penjelasan parameter detail serta nilai konfigurasi membantu menyelesaikan masalah rumit dan memahami alat secara menyeluruh. Kalau salah satunya hilang, itu sangat merepotkan. Namun untuk library yang sangat sederhana, contoh mungkin bisa menjelaskan semuanya

    • Baik contoh maupun dokumentasi referensi sama-sama diperlukan. Jika memungkinkan, menambahkan lingkungan REPL juga bagus. Jika contoh bisa langsung diubah dan diuji, banyak kekurangan dokumentasi bisa tertutupi

  • Framework Diátaxis menunjukkan dengan baik bahwa dokumentasi memiliki berbagai jenis dan masing-masing punya tujuan. Bukan soal mana yang “terbaik”, melainkan penting dipakai sesuai kebutuhan yang berbeda. situs resmi Diátaxis

    • Rasanya komentar ini seharusnya ada di paling atas. Agak frustrasi bahwa setelah diskusi sepanjang ini, baru kemudian ada yang menyebut Diátaxis. Menurut saya, contoh memang inti dokumentasi, tetapi lebih tepat dilihat sebagai “teknik dokumentasi” yang penting daripada “jenis dokumentasi” yang berdiri sendiri

    • Betul! Contoh (atau tutorial) adalah salah satu pilar dalam pembelajaran sistem. Saya tidak yakin siapa yang pertama membuatnya, tetapi tautannya mirip dengan tautan penulis di akhir artikel: > “Bahkan proyek besar pun jarang memiliki keempat jenis dokumentasi tersebut. Karena itu, ada kalanya orang ragu untuk menekan tautan ‘Documentation’” Saya menyukai dokumentasi yang berfokus pada penjelasan. Kalau memahami struktur atau alasan di balik suatu perilaku, maka contoh maupun tutorial jadi lebih mudah diterima. Jika penulis teknis atau pendidik yang sangat ahli membangun kerangka ini sejak awal, hasilnya sangat besar. Sebaliknya, referensi API paling dibutuhkan saat membuat wrapper atau implementasi kompatibel. Banyak proyek awalnya memang dimulai dari referensi API internal, dan dokumentasinya hanyalah proses membuka itu ke publik. lihat sistem dokumentasi divio

    • Konsep Diátaxis sangat bagus. Hanya saja, menerapkannya ke proyek nyata tidak mudah. Setiap proyek membutuhkan proporsi dokumentasi yang berbeda, dan menyediakan semua bentuk itu dalam satu situs web juga tidak efisien. Proporsi tersebut terus berubah mengikuti pertumbuhan dan tingkat keahlian komunitas. Saya berharap ada pendekatan yang lebih praktis. Dokumentasi adalah tugas yang sulit, dan semoga suatu saat ada solusi yang lebih baik. Saat ini, kualitasnya pada dasarnya ditentukan oleh seberapa banyak waktu dan keahlian yang diinvestasikan, dan kenyataannya biasanya keduanya kurang

  • Saya sangat sering merasakan masalah ini di Unity dan Unreal. Terutama dokumentasi node Unreal, yang sering kali hanya menampilkan tangkapan layar node dan menuliskan ulang namanya, tanpa menjelaskan sama sekali bagaimana cara memakainya. Di Unity juga sering begitu: saya mencari dokumentasi untuk tahu cara benar memakai suatu fungsi, tetapi isinya malah kosong. Kalau bisa, saya bahkan ingin ikut menyumbang contoh ke dokumentasi Unity

    • Dokumentasi Unreal yang buruk juga membuang banyak sekali waktu saya. Ada nuansa “kode adalah dokumentasi”, tetapi “penjelasan berupa tangkapan layar node” untuk Blueprint benar-benar sampai terasa konyol

    • Soal £JOB, saya penasaran apakah saat orang menulis $job mereka memaksudkannya sebagai pekerjaan yang menghasilkan uang, atau itu hanya diambil dari nama variabel biasa. Pada titik ini, pandangan saya tentang dunia jadi goyah

  • Saya sering memakai ImageMagick, dan dulu selalu mencari contoh lewat Google. Karena itu saya menggabungkan catatan pribadi saya menjadi kumpulan kecil contoh perintah. Saya juga menambahkan penjelasan rinci untuk tiap argumen. Saya merasa bukan hanya contoh seperti di tulisan blog ini yang dibutuhkan, tetapi juga penjelasannya. Masih tahap draf, tetapi untuk pekerjaan sehari-hari seperti resize, optimasi, dan layering, ini sudah sangat berguna. tautan publik catatan saya

  • Contoh kode bisa dijalankan sebagai unit test untuk mencegah dokumentasi menjadi usang atau rusak. Ini kelebihan yang tidak dimiliki bahasa alami

    • Sekarang dengan perkembangan LLM, misalnya, mungkin juga bisa dicoba memverifikasi akurasi dokumentasi API

  • Pendapat radikal: jika spesifikasi suatu metode tidak bisa dipahami secara intuitif hanya dari signature dan beberapa contoh representatif, berarti metode itu mencoba melakukan terlalu banyak hal. Saya juga tidak ingin mempelajari abstraksi yang membatasi gerak atau pengecualian yang rumit

    • Saya rasa tidak begitu. Contoh diperlukan bukan hanya untuk metode itu sendiri, tetapi juga untuk menunjukkan “bagaimana metode itu dipakai bersama metode lain”. Sekalipun semuanya bisa disimpulkan dari signature metode, tetap mudah melewatkan bagian penting seperti konfigurasi yang terlupa, proses persiapan, atau penanganan hasil. Karena itu, contoh tetap wajib
 
howudoin 2025-10-11

Di ekosistem Java dan budaya berorientasi objek, ada sangat banyak kalimat penjelasan yang tidak bermakna dan dokumentasi yang formalistis, dan bahkan di framework ekosistem Python yang mewarisi suasana itu, contoh penggunaannya juga cenderung sangat minim.

Contoh dokumentasi yang tidak bermakna
add(left, right) - menambahkan ruas kiri dan ruas kanan

Yang justru penting seperti tipe data parameter, bentuk pengecualian atau nilai hasil yang bisa dikembalikan, atau struktur cara kerjanya, malah tidak dijelaskan.

Kalau seperti man page bahasa C, hanya dengan penjelasan singkat pun tetap bisa dipakai, setidaknya dengan menebak dari nama fungsi dan nama parameternya.