[shizzy0]

Some of the best technical documentation I’ve ever written has straight up lies in it. Granted they were placed there in the service of distilling the most germane portions of the API I was trying to explain. But it made a huge difference once I decided my code in the library didn’t have to be my code in its documentation. I felt a little like a biographical writer who makes a composite character. But honestly I recommend trying it. Lie in your docs if it serves the greater goal of communicating what’s most important. Let the computer labor in the “truth” and its tediums.

[Noumenon72]

Do you mean you just left out required args, try-catches for checked exceptions, and so on, so the example would be easier to read? Did you put an asterisk on, like "* illustrative code: will not compile"?