begin to add some diagnostics handling
separate diagnose and docs

Naive implementation