4 ms·

Documentation doesn't exist to explain concepts and give tutorials so much as document functionality and possibly show examples of use.

hinkley 8y ago
It really doesn’t take that much extra work to explain why someone should care about the existence of a function. But it makes a huge difference in how approachable the library is, and how easy it is to learn (for instance, is this even the function I’m looking for?)
ergothus 8y ago
Why not? Document functionality and possibly showing examples is great (in general I'm a big advocate for examples), but those don't preclude explaining concepts. Some of the best documentation I've experienced covers concepts, some of the worst doesn't.
- nemo44x 8y ago
  I think one of the best reasons is because for users that have some experience with the technology want to be able to quickly find the documentation they're interested in. Can this API do X, for instance. And if it can what is required, what is optional and what are the ranges for values. I don't want to wade through lots of text and other clutter. I'd much rather have a tutorial or training be a different thing I can use when new to the technology.
  - ergothus 8y ago
    Those are valid points, but that just means the API documentation and the concept documentation should largely be separate documents, not that the documentation doesn't belong. In the best cases a link over to relevant concept docs from API and vice-versa is great, and occasionally enlightens even hardened devs ("wait, there's an API to do this directly?", "Wait, this concept was added and streamlined in the 3 years since I first used this product?", etc)
jhinds 8y ago
I think there can be different types of documentation (tutorials, reference, explanation, how-to guides). I came across this article a while back that goes over different categories and always re-read it when I know I'm going to have to write a bunch of documentation for something and always find it helpful to really think about the type that I need to write. In regards to the poster you replied to I think Oreilly books are in the explanation category of documentation instead of the traditional reference kind found online. The article I'm referring to: https://www.divio.com/blog/documentation/ https://www.divio.com/blog/documentation/
agibsonccc 8y ago
Documentation is a moving target. Depending on your project, you often have to mix background explanations with code samples. Fields evolve. New people show up. Documentation can never really be good enough. Books provide a way of filling in certain gaps in a structured way that gives people more background. Often times, people expect documentation to do more than this. I tend to agree with you, but it's not what end users end up needing a lot of the time.

hinkley 8y ago

It really doesn’t take that much extra work to explain why someone should care about the existence of a function. But it makes a huge difference in how approachable the library is, and how easy it is to learn (for instance, is this even the function I’m looking for?)

ergothus 8y ago

Why not? Document functionality and possibly showing examples is great (in general I'm a big advocate for examples), but those don't preclude explaining concepts. Some of the best documentation I've experienced covers concepts, some of the worst doesn't.

nemo44x 8y ago
I think one of the best reasons is because for users that have some experience with the technology want to be able to quickly find the documentation they're interested in. Can this API do X, for instance. And if it can what is required, what is optional and what are the ranges for values. I don't want to wade through lots of text and other clutter. I'd much rather have a tutorial or training be a different thing I can use when new to the technology.
- ergothus 8y ago
  Those are valid points, but that just means the API documentation and the concept documentation should largely be separate documents, not that the documentation doesn't belong. In the best cases a link over to relevant concept docs from API and vice-versa is great, and occasionally enlightens even hardened devs ("wait, there's an API to do this directly?", "Wait, this concept was added and streamlined in the 3 years since I first used this product?", etc)

jhinds 8y ago

I think there can be different types of documentation (tutorials, reference, explanation, how-to guides). I came across this article a while back that goes over different categories and always re-read it when I know I'm going to have to write a bunch of documentation for something and always find it helpful to really think about the type that I need to write. In regards to the poster you replied to I think Oreilly books are in the explanation category of documentation instead of the traditional reference kind found online. The article I'm referring to: https://www.divio.com/blog/documentation/ https://www.divio.com/blog/documentation/

agibsonccc 8y ago

Documentation is a moving target. Depending on your project, you often have to mix background explanations with code samples. Fields evolve. New people show up. Documentation can never really be good enough. Books provide a way of filling in certain gaps in a structured way that gives people more background. Often times, people expect documentation to do more than this. I tend to agree with you, but it's not what end users end up needing a lot of the time.