Post History

Source: https://writers.stackexchange.com/a/33590
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Working samples is an absolute must for all APIs. Period. Reference pages especially need one. Not including them overlooks the fact that API documentation is used by a range of people. It's short sighted by both the guys who says it and for the writing team to assume the documentation is only for the experienced developers. It has to appeal to both the experienced developer, the developer new to your product, and the inexperience developer. Each will divine from the suite what they need and ignore the rest.

You want to make the transition to your product as easy as possible and working, copy and paste is the best way. I'd like to see a API documentation suite using _only_ examples. The irony is, the most experience the developer, the less they read the documentation. At that point, they really only want code to copy and paste.

"Working sample" has different meanings, though. It doesn't have to be a fully functioning WinForms application. It doesn't need to be a "Hello, World." That can be saved for the tutorial or the comprehensive sample. Instead, a working sample can be a function that if pasted into a full application, will work almost without modification. MSDN does an excellent job of this. Each of their pages has a working sample.

Don't worry about the IDE. Pick a common one and stick with that. Don't worry about bloat. We're creating reference documentation that has to be complete. We have dictionaries that they keep adding words to each year, and no one complains.

Original score: 4