update documentation in line with standard format and built from markdown sources