Ask HN: Should documentation include sample code?

3 pointsnyjah1 comment

Should sample code be included in the documentation? I always find myself hitting up google after looking up the documentation just to see an example. Am I not grokking the documentation correctly? Are samples, even just one line, sacrilege? Any tips for understanding documentation like apple developer docs better?

View on HN

I've always loved the Lisp Hyperspec* way of doing it. On the sample link below, you'll notice it demonstrates how to use the print functions by showing equivalent write functions. Almost all of the built in functions and macros are described this way, and some even provide practical code snippets - whichever happens to make sense for the given reference.

* http://www.lispworks.com/documentation/HyperSpec/Body/f_wr_p...

Reply on news.ycombinator.com