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
Community Proposals
Community Proposals
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 See all your notifications »
Q&A

Post History

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

When documenting software API so others know how to access the various methods, what data structures are used etc, I like to document each bit in detail and also include, regardless of the coding l...

4 answers  ·  posted 6y ago by Lefty G Balogh‭  ·  last activity 3y ago by Monica Cellio‭

#4: Post edited by user avatar Monica Cellio‭ · 2020-07-10T01:02:47Z (over 3 years ago)
  • When documenting software API so others know how to access the various methods, what data structures are used etc, I like to document each bit in detail and also include, regardless of the coding language, a "hello world" style sample API client that shows how a few select methods and data items can be used for simple, life-like purposes. My argument is that first-time users can get started more easily and delve into the API services more quickly. However, from developers, I often get a rejection when I ask for a complete working code sample on various grounds:
  • - It would be IDE specific so it would not help people who use a different IDE.
  • - The audience is experienced developers who need no "hello world" to get started.
  • - It makes the document way too bloated and adds very little value.
  • So my question is, what is the added value, if any, of including simple, fully working code samples in API guides.
  • When documenting software API so others know how to access the various methods, what data structures are used etc, I like to document each bit in detail and also include, regardless of the coding language, a "hello world" style sample API client that shows how a few select methods and data items can be used for simple, life-like purposes. My argument is that first-time users can get started more easily and delve into the API services more quickly. However, from developers, I often get a rejection when I ask for a complete working code sample on various grounds:
  • - It would be IDE specific so it would not help people who use a different IDE.
  • - The audience is experienced developers who need no "hello world" to get started.
  • - It makes the document way too bloated and adds very little value.
  • So my question is, what is the added value, if any, of including simple, fully working code samples in API guides.
#3: Attribution notice added by user avatar System‭ · 2019-12-08T08:04:42Z (over 4 years ago)
Source: https://writers.stackexchange.com/q/33587
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by user avatar Lefty G Balogh‭ · 2019-12-08T08:04:42Z (over 4 years ago)
When documenting software API so others know how to access the various methods, what data structures are used etc, I like to document each bit in detail and also include, regardless of the coding language, a "hello world" style sample API client that shows how a few select methods and data items can be used for simple, life-like purposes. My argument is that first-time users can get started more easily and delve into the API services more quickly. However, from developers, I often get a rejection when I ask for a complete working code sample on various grounds:

- It would be IDE specific so it would not help people who use a different IDE.
- The audience is experienced developers who need no "hello world" to get started.
- It makes the document way too bloated and adds very little value.

So my question is, what is the added value, if any, of including simple, fully working code samples in API guides.

#1: Imported from external source by user avatar System‭ · 2018-01-25T14:41:28Z (about 6 years ago)
Original score: 9