adding some documentation (shock *and* horror)