Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read
Q&A

Post History

71%
+3 −0
Q&A What are the benefits of including complete working code samples in documentation

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 ...

posted 5y ago by ForEachLoop‭  ·  last activity 3y ago by System‭

Answer
#3: Initial revision by user avatar ForEachLoop‭ · 2019-12-08T08:04:44Z (about 3 years ago)
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.

#2: Attribution notice added by user avatar System‭ · 2019-12-08T08:04:44Z (about 3 years ago)
Source: https://writers.stackexchange.com/a/33590
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#1: Imported from external source by user avatar System‭ · 2018-01-25T16:39:08Z (about 5 years ago)
Original score: 4