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 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.
There are different types of examples and they serve different purposes. One type is the quick-start example that thi …
Working samples is an absolute must for all APIs. Period. Reference pages especially need one. Not including them overlo …
The purpose of API documentation is to explain how to use the API. Providing sample code of how to use key features is a …
I can understand the reasoning from both sides. A complete quick start is essential to ensure that the reader has suffic …