[Help Wanted] Update documentation guidelines

[it33]

Our existing guidelines are a bit out of date, would appreciate a PR to replace them. We can use the PR to discuss

[JeffSchering]

See PR #642

[jasonblais]

Closed via #642, thanks @JeffSchering!