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 is 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 science 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]
JavaScript: The Definitive Guide by David Flanagan.
[see 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.
The Mathematica Book is 2k pages. The last edition is written in 1999, included with every copy of Mathematica (aka the Wolfram Language). Wolfram stopped publishing hardcopies after this.
Xah Tutorials, Simple Style
My tutorial is mostly written in a simple style too. check them out: