5

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

  • 1
    Mostly off-topic, but not entirely irrelevant: I hate two-pane views. The only major software documentation I've seen with a two-pane view are the classic Java docs and the POSIX spec, which are both terrible to navigate IMHO. What are you trying to achieve by using a two-pane view that couldn't be solved with something more like e.g. Python's documentation (where the ToC is just a bunch of anchors into a big page)? – Kevin Mar 29 at 3:06
  • 1
    @Kevin we had to make a PDF of our whole doc set once for some contract; it's over 6000 pages. But we're also looking at more modern templates; this layout is years old and there are better options out there now. We've got somebody with actual UX background (not just the coursework some of us have had) who's going to help us out with this. – Monica Cellio Mar 29 at 3:15
  • I see that you find yourself unable to accept an answer to many of your questions on technical writing. Reflecting on this, I find it notable how I have absolutely no clue what you are talking about here. I neither write nor read poems or (screen)plays, but I'm familiar enough with both to understand questions about them and even answer a few. But with technical writing, I have not the slightest idea how you work and what it is that you do. Which makes me think that questions about technical writing maybe need their own community of experts to receive helpful answers and don't fit here well. – user37560 Mar 29 at 10:49
  • I understand (from the discussions on meta) that you and part of this community think that technical writing must be a part of it, but I consistently see that technical writing questions don't receive the same number and quality of answers as questions about writing fiction. Maybe they are not similar enough to be part of the same writing community? – user37560 Mar 29 at 10:51
  • 3
    I'm asking expert-level questions. If somebody asks an expert-level question about solving a problem in a sestina, I'd suspect you couldn't answer (same here). 62% of tech-writing questions here have accepted answers; poetry comes in a little lower, at 60%. Screenwriting is under 50%. SE tried a site specifically for technical communication and it failed in private beta; it was merged in here. – Monica Cellio Mar 29 at 14:15
5

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. (http://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:

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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.
  7. 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.

(No, I'm not back, but I get a notification for new tech comm topics and it is hard not to answer a question when you have written a whole book on the subject.)

2

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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.