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 (2005)]
• Spurious language comparison. [see Python Documentation, Author Masturbation (2005)]
• Unnecessary use of hip jargons. [see Jargons of Software Industry (2002)] [see Jargon REPL and Hackers (2013)]
• Juvenile jokes, hacker humor galore. For example, unix man pages. [see Tech Writing and Unix Humor (2012)]
• 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 (2005)]
• 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.
- https://gobyexample.com/
Go look. See its simplicity.
Another excellent example, is PHP documentation.
[see Examples of Quality Documentation in Computing Industry]
and JavaScript The Definitive Guide by David Flanagan. 2011, 2020.
Another excellent one is
- An Elementary Introduction to the Wolfram Language
- By Stephen Wolfram.
- 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: