Post History
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: Post edited
by
Monica Cellio
·
2020-07-10T01:02:47Z (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.
- 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
System
·
2019-12-08T08:04:42Z (about 5 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
Lefty G Balogh
·
2019-12-08T08:04:42Z (about 5 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
System
·
2018-01-25T14:41:28Z (almost 7 years ago)
Original score: 9