updated diagram as result of issues #8 and #25
provided some background about the discussion at issue #24