Programing Language Documentation Styles

By Xah Lee. Date: . Last updated: .

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 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.

JavaScript Definitive Guide by David Flanagan
[JavaScript Definitive Guide (6th ed.) By David Flanagan. @ Buy at amazon ]

[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. @ Buy at amazon ]

〈An Elementary Introduction to the Wolfram Language〉, online 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.

mathematica-books
The Mathematica Book By Stephen Wolfram. Buy at amazon

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:

If you have a question, put $5 at patreon and message me.