Teknik belgede örnek eksikliği, kullanıcıların en sık dile getirdiği şikayetlerden biri olmaya devam ediyor. Bir kavramı tanımlamak başka şey, onu anlaşılır kılmak başka şey. Belgeler çoğu zaman birincisini yapıyor, ikincisini yapmıyor. Teknik belgede örnek eksikliği şu durumda kristalleşiyor: Bir API referans belgesi, her parametrenin ne olduğunu eksiksiz açıklıyor. Ama kullanıcı şunu soruyor: Bunu gerçek bir senaryoda nasıl kullanırım? Bu sorunun yanıtı olmadığında, kullanıcı ya Stack Overflow'a gidiyor ya da deneme yanılmayla ilerliyor. İkisi de verimsiz. Bir örnek, sayfalar dolusu teorik açıklamadan daha hızlı öğretiyor. Çünkü beyin somut pattern'leri soyut kurallardan çok daha kolay özümsiyor. İyi seçilmiş bir kod örneği, hem ne yapıldığını gösteriyor hem de nasıl yapılacağına dair zihinde şablon oluşturuyor. Teknik belgede örnek eksikliğinin üç tipik formu var: Hiç örnek yoktur. Örnek çok basit, gerçek dünyayı yansıtmıyor. Ya da örnek çok karmaşık, neyi anlatmak istediği belirsiz. Her üçü de farklı biçimde zarar veriyor. Etkili örnek nasıl olmalı? Gerçekçi bir senaryodan yola çıkmalı. Gerekli minimum kodu içermeli. Hem çalışan hem de hata durumunu göstermeli. Yorumlarla açıklanmalı. Teknik belgede örnek eksikliğini gidermek, aslında belgenin gerçekten kullanılır hale gelmesi anlamına geliyor. Teori olmadan pratik olmaz ama pratik olmadan teori kalmaz.