Programing Language Documentation Styles (2015)

By Xah Lee. Date: . Last updated: .

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 by Example By Mark Mcgranaghan. At https://gobyexample.com/

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

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: