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 (2002)〕 〔see Jargon REPL and Hackers (2013)〕
• 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 (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: