23

Whenever I come across a new API or programming language or even simple Linux man pages, I always (ever since I remember) avoided them and instead lazily relied on examples for gaining understanding of new concepts.

Subconsciously, I avoid documentation/APIs whenever it is not straightforward or cryptic or just plain boring. It's been years since I began programming and now I feel like I need to mend my ways as I now realize that I'm causing more damage by refraining from reading cryptic/difficult documentation as it is still a million times better than examples as the official documentation has more coverage than any example out there. Even after realizing that examples should be treated as "added" value instead of the "primary" source for learning.

How do I break this bad habit as a programmer or am I overthinking?

Improve this question
3
  • 3
    I don't think it is a bad habit. I always start with the examples and then read on the documentation as needed.
    – kaptan
    Oct 18, 2013 at 21:47
  • 1
    a million times better than examples as the official documentation has more coverage - Not always, I've found some great undocumented features in the past through examples
    – Izkata
    Dec 11, 2013 at 22:18
  • Documentation should communicate concepts with examples. I generally consider docs that don't as failures to document.
    – svidgen
    Apr 30, 2015 at 15:30

4 Answers 4

Reset to default
30

The habit of relying in preference on examples has nothing wrong: for you, it's just the fastest way to get your answer. Moreover, examples are visual. It's easier to parse visually an example rather than read paragraphs of text and extract the information you need.

Example:

In order to list the products, one should use Index action of the Products controller, given that GET is the only possible verb here (see [Affecting products] for more information about the actions used to create, modify and delete the products from the database).

In order to obtain detailed information about a specific product, append its unique identifier to the end of the URI. If you want to get the list of every product available, don't append anything. You may also use filters, as described in the [REST filters for selecting data] section of the manual. Note that the list of products is limited to one thousand items. [Pagination] can be used to walk through the entire list, given that each page is still limited to one thousand items.

You may also want to force the service to refresh the quantities in stock. This is done by setting the refresh-quantities to one.

is detailed, but boring and barely readable. The fact that you need to follow links makes things even worse. If we append some samples, it becomes much easier to understand:

GET Products/Index/
GET Products/Index/12345/
GET Products/Index/?skip=100&take=20
GET Products/Index/?category=12
GET Products/Index/?price=0..39.90
GET Products/Index/?category=12&skip=100&take=20

The fact that you use only the examples may be a problem. Don't plainly stop using the examples, but remember that once you got the idea, a more verbose documentation may help. For example, the sample above doesn't show that the list of products is limited to 1 000: you have to read the documentation for that.

When do you know that you should read the documentation?

Every time the API or the library is not behaving as you expected. For example, you grab the sample and do:

GET Products/Index/?skip=6000&take=3000

For some reason, it returns less than 3 000 items, while you have over twenty thousand products in your database. Here, the API is not behaving like you expected, so it's a good time to read the detailed documentation.

Improve this answer
2
  • Makes perfect sense. Always get back to the documentation even if the way is paved by examples!
    – user6123723
    Oct 15, 2013 at 17:45
  • 2
    In addition, sometimes you find out really simple, elegant, and easy ways to do things by thoroughly reading the docs that you probably will never find an example of, because no one else would think to put those features together in that way (they don't have your use case to solve).
    – Amy Blankenship
    Oct 19, 2013 at 3:50
10

Information provided by documentation falls in three catgeories:

  • Recipe.
  • Reference.
  • Expert knowledge.

Recipes or example makes a bridge between the problem domain and the functionalities of the software. Reference describes completely some functionality and is useful if you want to adapt a recipe to a specific case.

(Expert knowledge maps concepts of the problem domain to concepts of documentation, it is useful if concepts can be expressed in several manners or if users of the software are not experts in the field.)

How do I break this bad habit as a programmer or am I over thinking? Any wisdom from fellow programmers is appreciated.

I do not think that your habit is bad. When you learn an API, you first get an idea of which problems can be solved and which methodologies are provided with the help of Recipes (your examples). Reference documentation then helps you to fine tune the methodologies to special cases.

Improve this answer
1
  • 3
    Back in the days of the dinosaurs, when every program had printed, professionally written documentation, there were usually two books: the Reference Manual and the User Guide. The Reference Manual was the definitive specification of what everything did, and the User Guide was a collection of use cases. Both were important and useful.
    – Ross Patterson
    Oct 19, 2013 at 1:13
2

Examples are documentation. I don't think it is bad from a getting familiar with the API standpoint. If it is the only documentation that you look at then it can be an issue. Most examples skimp on error checking which can lead to overly brittle code if you don't go back and pick up the missing pieces from the reference documentation.

Improve this answer
1
  • Awesome. My primary concern has been that I only make use of the knowledge derived from the examples and since there's lot more value in the documentation and when I miss reading it, I fail to make use of that. I should take this more seriously now that I understand the problem.
    – user6123723
    Oct 15, 2013 at 17:48
1

Different people learn better in different ways. Some people are like you and learn better from examples. Some people are like me and learn better from detailed documentation. Having both in the documentation seems to cover most developers pretty well. Talk to a teacher, they can tell you half a dozen ways people learn.

Improve this answer

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.