4 ms·

I'd say only overly verbose documentation is bad. If a situation exists in which someone will access your code without the source code right in front of them;

I'd say only overly verbose documentation is bad. If a situation exists in which someone will access your code without the source code right in front of them; ie. it's a library that will be and depended upon by others, consider: 1) They probably will not compile or read your source code, so no matter how elegant your code is, they'll only see the exposed API, and no how your function works wont be obvious. 2) Automatically generated documentation is usually very poor for unannotated code. 3) Writing simple intuitive APIs is actually very difficult, and the chances that you'll get it right every time are virtually zero. Maybe internal functions can be 'self documenting', but it's a silly to say documentation, in general, is bad. Public APIs require documentation; if you don't document it, and the person who has to use it has to hunt down a copy of the source code to find out how to use it, trust me, they will curse you for it, not thank you for writing simple elegant code.

AndrewDucker 13y ago
I'd say the opposite. Nobody will read your documentation. They will be able to see the API, so make sure that it's well designed, and as easy to use as possible (much easier in languages/IDEs with autocompletion). And they will use code snippets, so make sure that you make those available. Feel free to walk people through the process of using those snippets, so they can understand them, but 99% of devs are just looking for some code they can splat in and get their system working. A great example of this is the Quick Setup guide for Persona: https://developer.mozilla.org/en-US/docs/Mozilla/Persona/Quick_Setup https://developer.mozilla.org/en-US/docs/Mozilla/Persona/Qui... Which walks you through what you need to do, giving you code that you can use at every step.
- noir_lord 13y ago
  Agree completely. Another good example is these guys https://gocardless.com/docs/ https://gocardless.com/docs/ If I'm looking at an external service/API for use in one of our products the first thing I look for from a technical perspective (is this priced right) is good code samples of API usage, then I look take a look a whistlestop tour through the docs (mostly to get an idea of quality and completeness). At that point I might whip up a simple project against their API (if they make it easy to do and without having to pay...) and if I like it then I'll buy, Another good example I ran into recently was Nexmo, very easy to use and good docs.
- shadowmint 13y ago
  ...so you're saying, no one will read the documentation, because they'll all be looking at the documentation? You've lost me I'm afraid. (unless you're saying that api documentation, specifically, isn't very useful compared to say, examples, in which case, you're agreeing with me, because useless api documentation is what you get when you run a documentation tool over a code base without annotations...)
  - TeMPOraL 13y ago
    > ...so you're saying, no one will read the documentation, because they'll all be looking at the documentation? I think he means that devs won't be reading documentation like a book, chapter by chapter, trying to comprehend what API does, but instead they will look at tutorials and code snippets, and enter your documentation at random points via Google / StackOverflow links, mostly in cases when something is not working.

AndrewDucker 13y ago

I'd say the opposite. Nobody will read your documentation. They will be able to see the API, so make sure that it's well designed, and as easy to use as possible (much easier in languages/IDEs with autocompletion). And they will use code snippets, so make sure that you make those available. Feel free to walk people through the process of using those snippets, so they can understand them, but 99% of devs are just looking for some code they can splat in and get their system working. A great example of this is the Quick Setup guide for Persona: https://developer.mozilla.org/en-US/docs/Mozilla/Persona/Quick_Setup https://developer.mozilla.org/en-US/docs/Mozilla/Persona/Qui... Which walks you through what you need to do, giving you code that you can use at every step.

noir_lord 13y ago
Agree completely. Another good example is these guys https://gocardless.com/docs/ https://gocardless.com/docs/ If I'm looking at an external service/API for use in one of our products the first thing I look for from a technical perspective (is this priced right) is good code samples of API usage, then I look take a look a whistlestop tour through the docs (mostly to get an idea of quality and completeness). At that point I might whip up a simple project against their API (if they make it easy to do and without having to pay...) and if I like it then I'll buy, Another good example I ran into recently was Nexmo, very easy to use and good docs.
shadowmint 13y ago
...so you're saying, no one will read the documentation, because they'll all be looking at the documentation? You've lost me I'm afraid. (unless you're saying that api documentation, specifically, isn't very useful compared to say, examples, in which case, you're agreeing with me, because useless api documentation is what you get when you run a documentation tool over a code base without annotations...)
- TeMPOraL 13y ago
  > ...so you're saying, no one will read the documentation, because they'll all be looking at the documentation? I think he means that devs won't be reading documentation like a book, chapter by chapter, trying to comprehend what API does, but instead they will look at tutorials and code snippets, and enter your documentation at random points via Google / StackOverflow links, mostly in cases when something is not working.