Document the build system

Review 1207 by @mglukhovsky
Closes #1946