Post History
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 --...
#4: Post edited
by
Monica Cellio
·
2020-11-17T03:59:15Z (about 4 years ago)
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).
- 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.
#3: Attribution notice added
by
System
·
2019-12-08T11:33:51Z (about 5 years ago)
Source: https://writers.stackexchange.com/q/44170 License name: CC BY-SA 3.0 License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision
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: Imported from external source
by
System
·
2019-03-29T02:32:37Z (over 5 years ago)
Original score: 5