Documentation: Clarify declaration files and the declare keyword #23262
Description
TypeScript Version: 2.8.0
Search Terms:
document declaration files
** Issue**
It doesn't look like you actually define what a declaration file is in your documentation. For instance, your introduction to these at https://www.typescriptlang.org/docs/handbook/declaration-files/introduction.html tells me you're going to help me learn how to write them, but not what they are or why I'd want one. But, I don't think this makes it easy for a newbie to understand.
Similarly, you don't seem to explain when the declare keyword is, or when it should be used (as far as I can tell, it is used when you need to tell the compiler that the module/library/whatever has a value of some type).
You also seem to make some references to the global namespace (declare global { ... })), but don't seem to directly explain it anywhere.
Code
n/a
Expected behavior:
n/a
Actual behavior:
n/a
Playground Link:
n/a
Related Issues:
n/a