diff --git a/compile_commands.json.md b/compile_commands.json.md
new file mode 100644
index 0000000..8821f98
--- /dev/null
+++ b/compile_commands.json.md
@@ -0,0 +1,104 @@
+[Guillaume Papin(@Scarcasm)](https://github.com/sarcasm) has [a thorough article about compilation databases](https://sarcasm.github.io/notes/dev/compilation-database.html).
+
+### [CMake](https://cmake.org/)
+
+```zsh
+% mkdir build
+% (cd build; cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=YES ..)
+% ln -s build/compile_commands.json
+```
+
+### [Build EAR](https://github.com/rizsotto/Bear)
+
+Bear is a tool that generates a compilation database for clang tooling. It can be used for any project based on `Makefile`.
+
+```zsh
+bear make
+# generates compile_commands.json
+```
+
+### [scan-build](https://github.com/rizsotto/scan-build)
+
+scan-build is a python package that can generate a compilation database for clang tooling (uses Bear as a backend). This too can be used for any project based on a `Makefile`.
+
+```zsh
+intercept-build make all # generates compile_commands.json from the `make all` ruleset
+```
+
+### [Ninja](https://ninja-build.org/)
+
+```zsh
+# Format: ninja -t compdb rule_names... > compile_commands.json
+ninja -C out/Release -t compdb cxx cc > compile_commands.json
+```
+
+### [Waf](https://waf.io/)
+
+Load the `clang_compilation_database` tool in your wscript:
+
+```python
+def configure(conf):
+    conf.load('clang_compilation_database')
+```
+```
+./waf configure build
+ln -s build/compile_commands.json
+```
+
+### stdout of an external command
+
+You may use the initialization option `"compilationDatabaseCommand"` to provide the JSON compilation database. cquery will read its stdout rather than read `compile_commands.json`. This may be useful when cquery cannot parse the `compile_commands.json` correctly (e.g. MSVC cl.exe, Intel C++ Compiler options)
+
+```sh
+# extra command line option
+'--init={"compilationDatabaseCommand":"mycompdb"}'
+```
+
+```elisp
+(setq cquery-extra-init-params '(:compilationDatabaseCommand "mycompdb"))
+```
+
+Suppose the project is at `/tmp/c`, `mycompdb /tmp/c` will be executed with stdin=initializationOptions and the stdout should be a JSON compilation database.
+
+You may use this shell script as a starting point:
+```zsh
+#!/bin/zsh
+# mycompdb /tmp/c
+cat >> /tmp/initialization-options
+cat <<e
+[ { "arguments": [ "c++", "a.o", "a.cc" ],
+    "directory": "/tmp/c", "file": "a.cc" } ]
+e
+```
+
+An example to scrub Intel C++ Compiler options:
+```zsh
+#!/usr/bin/env python3
+import json
+import os
+import sys
+with open(os.path.join(sys.argv[1], 'compile_commands.json')) as f:
+    db = json.load(f)
+    for entry in db:
+        args = entry['arguments']
+        try:
+            # Intel C++ Compiler option that is unknown to clang
+            args.remove('-xHost')
+        except ValueError:
+            pass
+    json.dump(db, sys.stdout)
+```
+
+## Examples
+
+### Linux kernel
+
+```zsh
+wget 'https://git.archlinux.org/svntogit/packages.git/plain/trunk/config?h=packages/linux' -O .config
+yes '' | make config
+bear make -j bzImage modules
+```
+
+## Misc
+
+`compile_commands.json` should reside in the project root because Emacs/VSCode plugins use it to indicate the project root, which will be used to initialize `InitializeParams.rootUri`.
\ No newline at end of file