For HTML documentation sets, are there meaningful guidelines for topic length?
We produce a large HTML documentation set with the conventional two-pane view: expandable table of contents on the left, selected topic on the right. When you select a topic, if it has subtopics -- that is, sub-pages in the table of contents -- the TOC automatically expands to show them. Because our documentation set is large and complex, nesting can go 5-6 levels deep.
There have been some disagreements in our group about topic length and in-topic subheadings. Some argue that we should keep topics relatively short (a screenful or two, which obviously depends on screen size) because long pages (with correspondingly-small scrollbar selection) are discouraging, and that so long as we have good navigation links, it's ok to make subtopics with their own pages. Others argue that having to navigate to pages more often, even if the linking is good, is more annoying for users and bloats the table of contents, and people can handle long pages in technical documentation. An additional consideration is search; our documentation is posted publicly and a lot of our traffic comes from Google.
Are there generally-accepted conventions, ideally supported by user studies, about page length vs. TOC complexity? How can we decide how long is too long?
An example might help. Consider a reference page for a complex SQL statement, one that has 20-30 parameters, a bunch of restrictions, and a dozen or so examples. One camp would say that this is one topic, albeit a large one; the other camp would present the description and syntax summary on a top-level page with sub-pages for the parameter descriptions, restrictions, and examples. For calibration, as a single topic it would be rather longer than most Unix man pages I've seen (in part because man pages are quite compact and our reference pages aren't).
In addition to the TOC in the sidebar, each topic has breadcrumbs (path from root to here) and previous/next links at the top and bottom of the topic.
2 answers
I spent so much time trying wrestling with just this problem that I wrote a book about it: Every Page is Page One: Topic-based Writing for Technical Communication and the Web. (https://xmlpress.net/publications/eppo/).
The answer I came up with after much research and experimentation is that it is not about length, but about certain characteristics of the topic, which I distilled into seven principles:
- A topic should be self contained. That is, it should not be written as if it followed immediately from any other topic, or as if it will be followed immediately by any given topic. It should be written as the first and possibly last page the reader will see.
- A topic should have a specific and limited purpose. This does not necessarily mean it answers the whole of the reader's question because reader's questions, and their existing knowledge, vary too widely for that, but rather that it should complete one whole step in the reader's journey to correct action, just as a commuter train takes people reliably from their suburban station to the downtown station. Getting them from house to station and from station to office may be the work of other topics.
- A topic should conform to a type. People usually need the same types of information to complete tasks of the same type. All recipes, for instance, have the same basic structure. Conforming to a type ensures that you are providing the right information for a topic to achieve its specific and limited purpose.
- A topic should establish its context. Because people do not read documents or documentation sets in order, they may start at any topic, and if a topic does not establish its context, they will be lost. Any topic that cannot establish its context clearly is not a full topic but a fragment of something else.
- A topic should assume the reader is qualified. If you start adding information for readers who might not be ready, your topic will grow into an unruly and impenetrable mess. If readers are not ready, refer them to other topics to get them up to speed.
- A topic should stay on one level. Some people prefer to start with the details and work up to the big picture. Some want the big picture first. Let them choose for themselves by keeping each topic on the same level and providing links to related topics.
- A topic should link richly to other topics. If you don't link richly, people will have a hard time finding related information and you will be tempted to violate the other principles.
0 comment threads
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 comment threads
0 comment threads