updated docs to include guidelines, changes and various suggestions from Andrey Semashev, JeffLee Hellrung and others