Programing Language Documentation Styles (2015)
Worst Writing Styles of Programing Language Documentation
The worst programing books are those that:
• Verbose intro tales, author personal rambling. Official python tutorial and documentation of this ilk. 〔see Python Documentation Problems〕
• Spurious language comparison. 〔see Python Documentation Author Masturbation〕
• Unnecessary use of hip jargons. 〔see Jargons of Software Industry〕 〔see Jargon REPL and Hackers〕
• Juvenile jokes, hacker humor galore. For example, unix man pages. 〔see Tech Writing and Unix Humor〕
• Engineering practice patronization, telling you about patterns, agile, unit-test. Official Java Tutorial circa 2000 is epitome of this ilk. 〔see Official Java Tutorial on Interface, the Inanity〕
• Idiom institution. Telling you how you should write your code. Perl books are epitome of this ilk. 〔see Perl Books Survey 2002〕
• Gratuitous computer engineering info on compiler-this-that, singing of stacks, references, memory and CPU architecture, “garbage collection”.
Good Documentation Style
There several good doc styles. One of them is: to the point, concise, precise, full of examples.
Here are some of good examples of this style:
Go look. See its simplicity.
Another excellent example, is PHP documentation.
〔see Examples of Quality Documentation in Computing Industry〕
and Book Review: JavaScript by David Flanagan
Another excellent one is
see also http://blog.stephenwolfram.com/2015/12/i-wrote-a-book-to-teach-the-wolfram-language/
and in general, Mathematica's documentation by Stephen Wolfram.
Xah Tutorials, Simple Style
My tutorial is mostly written in a simple style too. check them out: