docs: document header structure

Reference: https://github.com/neovim/neovim/issues/6371

runtime/doc/dev_style.txt

@@ -41,6 +41,43 @@ All header files should start with `#pragma once` to prevent multiple inclusion.
         #pragma once
 <
 
+Headers system ~
+
+Nvim uses two types of headers. There are "normal" headers and "defs" headers.
+Typically, each normal header will have a corresponding defs header, e.g.
+`fileio.h` and `fileio_defs.h`. This distinction is done to minimize
+recompilation on change. The goal is to achieve the following:
+
+- All headers (defs and normal) must include only defs headers, system
+  headers, and generated declarations. In other words, headers must not
+  include normal headers.
+
+- Source (.c) files may include all headers, but should only include normal
+  headers if they need symbols and not types.
+
+Use the following guideline to determine what to put where:
+
+Symbols:
+  - regular function declarations
+  - `extern` variables (including the `EXTERN` macro)
+
+Non-symbols:
+  - macros, i.e. `#define`.
+  - static inline functions, but only if its function declaration has a
+    `REAL_FATTR_ALWAYS_INLINE` attribute.
+  - typedefs
+  - structs
+  - enums
+
+
+- All symbols must be moved to normal headers.
+
+- Non-symbols used by multiple headers should be moved to defs headers. This
+  is to ensure headers only include defs headers. Conversely, non-symbols used
+  by only a single header should be moved to that header.
+
+- EXCEPTION: if the macro calls a function, then it must be moved to a normal
+  header.
 
 Constants ~