This is not based on studies. It is instead just the subjective experience of plainly and painstakingly having to read through documentations of different sorts throughout the years.

Documentation is mainly written for the users of the technology. These have typically different and varying skills. You need to identify these levels before you can address your initial question.

Organizing the docs

Let's imagine that there are three levels: basic (i.e. end-user, and I'd argue there is always a basic user level), advanced (still and end-user but may wish for some customizations), and dev (the person that will eventually modify the code). In this sense, I always found that Matlab docs were really well organized both for a basic and and advanced user, in contrast to R or Python docs.

Documentation for any item should be separated for these three levels. The core of the docs are the pages for the basic user. As a matter of fact you can probably envision it as a graph, where the documents for the basic users are the main body of the connected graph, with links between items. From each item there is also a tree, nearly unconnected to the rest of the documentation, expanding into advanced and dev topics.

Basic documentation

The main access to each piece of documentation should always occur through the basic user doc. It is nearly pointless to dump a reader straight to some advanced parameters if they need to know or refresh their memory on what the item is. Basic user docs should be brief, with a very short title; written under the assumption of default parameters, and only explaining in layman's terms the function of parameters that are required (i.e. only those that do not have a default). Some useful examples should be provided. This boils down to:

1 title
1 paragraph to say what the function does
at least 1 usage example, with a line to describe the intention, and the expected output
internal references (a reasonably small number)
essential external references, if needed.

more than this should be superfluous, otherwise your item could probably be grouped/broken down into smaller, simpler, more useful/powerful items.

A note: This is very context dependent, but if you look at the number of required parameters you can get a feeling of what the median is. Let's imagine it is 3. At this point, a basic function that requires more than 5 parameters is probably missing the point, or it has unspecified defaults that should be set.

Advanced and dev documentation

The advanced doc is probably what you have been describing in the question. A page containing a description of each parameter, with usage examples. This document may be further split into: parameters for which there is a reasonable expectation of changing them (e.g. sorting by some feature, or showing hidden items), and parameters that are available but probably left untouched most of the times (e.g. the desired numerical precision on some math functions).

The dev doc shows the inner working of each item. This is as long as you need. The person dwelling on these docs will probably know what they are looking for. I am not sure you want to go to such a level of details.

Interface

Links, oh links!

I would say that interfaces follow a bit the taste of the time. In my opinion a fixed side bar taken space away from your documentation, and it may force to wrap lines that would otherwise be in one piece. I agree instead with Kevin's comment: Python documentation, the one with fixed anchors, provides a very light and unobtrusive way of navigating.

TOC

TOC is also usually meant for the user to be read, rather than an exercise for the curator to create beautiful topiary art. I think that on this website you allow up to three levels of headings. I would keep it equally simple. Group your items by some global categories, not exceeding half page if you were to list them. For each of them add some sub-categories, again not exceeding half page, and for each sub-category, you can probably expand on two or three more sub-sub. No need to list items in the TOC. Actually, more than a TOC, what often helps is an alphabetically sorted index of items in the printed version, with nested references, or a good search function in the online version of the docs.

---

(0)

Login to post a comment!