A quick-ish post buy Eric Holscher, of Read the Docs. I agree with all of this, therefore I am linking to it. tl;dr: Have a website, not a directory of text files. Use prose, not auto-generated bullshit. Use permalinks. Have the language and version # in your URLs. Keep docs keyed to version #s.