Documentation update, especially to the "how it works" article