How to Judge the Quality of a Programing Language Doc (2018)
How to Judge the Quality of a Tech Documentation?
((ease of understanding) + (ease of finding answer/topic) + correctness + (lots pertinent code examples)) / (number of words)
- golang ≿ ruby ≿ php ≿ scheme ≿ java ≿ emacs lisp ≿ perl ≿ clojure ≿ python ≿ ocaml ≿ haskell ≿ JavaScript
- all the ones before java, are superb. but starting with emacs lisp, it's shit.
- it's not a smooth difference of quality of doc among langs.
- emacs lisp doc, was, superb, in 80s and 90s. It is, superb tech writing. However, it's the world's most worst organization. Basically, u can't find anything unless u have red the entirety of 1k pages of it.
- so, if we consider say post y2k, then, emacs lisp doc, would be very bad.
- the above is some fine points in judging a doc.
- e.g. we can judge on the pure technical writing aspect, the precision aspect, the organization aspect (critical. else, u can't find things u looking for), formatting aspect (critical, because lots syntax issue and code example need it. e.g. which param are optional, what are defaults, how u mention aliases, alt syntax, how u format operators, etc)
- and or, just in general of all of the above.
- also, each of the above criterion, many of which, has to do with the language in particular. for example, say wolfram lang, or php of 2000s. basically, everything is a function. so, if u have a way, to simply list and or find a function name, then it solves most of the organization issue. php did this with the particular url format with function name at the end, plus a search function on their site. similar is wolframlang.
- lisp, could do the same. but emacs lisp and common lisp failed miserably.
- now, if u have a lang with complex ad hoc syntax each have diff semantics, such as C C++ perl python, then, organization of the doc becomes more critical.
- java, solves this perfectly, also due to the lang. because, the whole lang sits on a class tree. Coding java is about creating class and objects on this tree. So, Java's doc, has this class organization, which made it super easy to find what u need. so, it also solves the organization problem.
- ruby, is somewhat similar. ruby has a strong tree structure of its function or methods. (though, i haven't work with ruby much)
Microsoft Shutdown Its JavaScript and Redirect to Mozilla Site (2017)
found the source!!!
- Indeed. My observation is correct.
- The mega corps, decided, in 2017, to put all their money into mozilla doc.
- This is why, since 2017, mdn doc went from shit to one of the best.
- And increased in size by few times, actually.
- It essentially became, THE, doc, for JavaScript and all related web tech.