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