Programing Language Documentation Styles
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]
• Juvinile 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 by Example By Mark Mcgranaghan. At https://gobyexample.com/ , accessed on 2016-08-23 ]
Go look. See its simplicity.
Another excellent example, is PHP documentation.
[see Examples of Quality Documentation in Computing Industry]
and JavaScript Book by David Flanagan, and Man-made Complexity in Computer Language
Another excellent one is
[An Elementary Introduction to the Wolfram Language By Stephen Wolfram. At http://www.wolfram.com/language/elementary-introduction/ ]
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: