Download Reference Manual
The Developer's Library for D
About Wiki Forums Source Search Contact

Documenting the Tutorials

Above all, tutorials should be simple and clear. One should strictly avoid incorporating concepts that serve to complicate the explanatory text, and/or the code examples. Library tutorials should convey, or focus upon, the concepts behind the library rather than those behind a specific usage of the library.

Complexity can also be manifested in the examples themselves; try to avoid incorporating long streams of code in the tutorial; if readers prefer to peruse extensive coding samples, they can browse through the library source (which uses itself). Thus, try to keep example code to just a reasonably small number of lines: something to illustrate a point being discussed. This is a key element ~ any code should primarily be illustrative, and illustrations are usually intentionally simple.

Perhaps one reasonable measure of complexity might be the number of imports required? For tutorial examples, this should typically be a rather small number.

If you find the tutorial is instead documenting a complete program, sub-system, or "case-study", try to isolate key elements therein and talk about those specifically (typically those that relate to the library). You shouldn't have to list the entire code within the discussion; instead, full code listings can be attached as files to the bottom of the page. Look at how this is done in magazines, and think about how an interactive environment (such as the Wiki) can remove some of the 'noise' to make the article more readable and/or enjoyable.

Structure

The exact nature of the tutorial might make some of this unnecessary, or maybe it will need to be changed for clarity. A medium sized tutorial should have these elements, though:

Title

A paragraph with an introduction to the subject of the tutorial

Domain specific introduction optional

A paragraph or two on any prerequisite knowledge to the subject, for instance some words on the technicalities that makes this tutorial or package in question necessary.

Body

The main part of the tutorial, can be subdivided if it is large.

Summary

A paragraph summarizing what has been shown in the tutorial.

Additional Notes / See also

Points of interest, links to deeper material, tangential information etc

See Standard formatting for how to format headings, symbols, code and other elements in the tutorials.