Distinguishing type Explanation from type Reference

[ToBeJazz]

A software "unit"'s (aka module) description of the problem that it is solving, and the high-level description of the solution that it is providing - would you count this as Explanation type documentation or Reference?

[evildmp]

If it's really high-level and broad (e.g. "Django is a programming framework that helps you build web applications in Python", or "The logging module provides a centralised system for capturing, routing and storing application messages, such as internal errors and warnings"), then it's so broad that it's more like the description on the box of the product or the back of the book - just some basic information to help the passer-by understand what it is that they are looking at.

In fact a sentence like that could be dropped in to an explanation section, a reference section or almost anywhere, just to provide a bit of introductory orientation, a little preamble so that it's clear to the reader what they're going to be reading about.

---

However let's assume that it's a bit more detailed than that. Consider, say, a specialised attachment for a power tool, that's made of some advanced material to a complex design, and is intended for a specific kind of application.

You, as a user, want two different kinds of theoretical knowledge about it.

You want understanding. You want to know what it's for, and when to use this rather than another tool. You want to know why you should use it. It might help you to know what kinds of tools it supersedes or is related to. You want to know what problems it solves. All this will help you place it in context.

You also want information. You want to know which models it's compatible with. You want to know how much power it requires, or what materials it is dangerous to use it with. You want to know the maximum permitted length of operation, or about the wear indicators on the blades. And so on.

The first kind of knowledge comes from explanation. It's the kind of thing you might get if you were chatting in your lunch break with a colleague about the new tool.

The second kind of knowledge comes from reference. It's the kind of thing that would be contained in tables of numbers in a specifications leaflet accompanying the tool.

In this case, what you're describing is clearly explanation, because the user need that it meets is the need to understand.

This is always the key, to ask: what need does [or should] this kind of documentation meet?

[ToBeJazz]

Thanks, that makes total sense to me. This structure of yours with four types of documentation has really helped me to understand what documentation is.

I'm thinking there are probably a few other concepts/terms that also needs this "clarification through separation" method applied to them..