Programming language docs structure

Some suggestions for documentation from learning several programming languages – along the lines of a quasi-formalised structure.

There is something of a problem with many languages it seems:

• languages are rather complex software artifacts,
• they are primarily for other people to use,
• the documentation is often somewhat on the casual and exiguous side.

The third does not fit well with the other two!

So what is needed is: common-usage-oriented documentation.

———

In creating information we ought to do two things generally: attend to what we want, and exploit commonalities. And for language docs that means looking at:

• how the language is used in practice,
• and de facto standard or common features of most languages.

Documentation following those makes the language and its features:

• easier to use by looking-up things on demand,
• easier to learn because of near familiarity.

Since this proposition is supposed to fit all/many potential languages it is built around how programming is done in general. And that is, most broadly, about two things: defining data, and defining algorithms. And those are detailed by features found commonly in other existing languages.

So, arrange documentation into these kinds of sections and parts:

• Data
  • Primitives – primitive data types (bool, number, string, etc.)
  • Compounds – compound data types (array, list, dictionary, etc.)
  • Declaratives – variable and value definitions
  • Modularising – packaging and namespacing
  • Typing – type combiners (sums, products, etc.)
• Algorithm
  • Operations – built-in operations (+ | < etc.)
  • Control – algorithmic/sequence structure (function, condition, iteration, etc.)
  • Comprehensions – compound-data processing functions (map, fold, etc.)
  • Parallelising

This would reasonably fit most languages. And even where a language significantly diverges it is still helpful: because it clarifies such differences with respect to what is familiar.

———

Whatever programming task you have you will be asking the same basic kind of questions: how do I represent a string, or collection of them?, how do I specify an iteration, or condition? The form of the documentation fits these abstract structural questions, so the answers for any particular language can easily be found. And one can also easily see the broad differences in languages by noting how these general sections of the documentation are filled (or added to).

———

Related:

• ‘A Core Of Programming’