Communities

Writing
Writing
Codidact Meta
Codidact Meta
The Great Outdoors
The Great Outdoors
Photography & Video
Photography & Video
Scientific Speculation
Scientific Speculation
Cooking
Cooking
Electrical Engineering
Electrical Engineering
Judaism
Judaism
Languages & Linguistics
Languages & Linguistics
Software Development
Software Development
Mathematics
Mathematics
Christianity
Christianity
Code Golf
Code Golf
Music
Music
Physics
Physics
Linux Systems
Linux Systems
Power Users
Power Users
Tabletop RPGs
Tabletop RPGs
Community Proposals
Community Proposals
tag:snake search within a tag
answers:0 unanswered questions
user:xxxx search by author id
score:0.5 posts with 0.5+ score
"snake oil" exact phrase
votes:4 posts with 4+ votes
created:<1w created < 1 week ago
post_type:xxxx type of post
Search help
Notifications
Mark all as read See all your notifications »
Q&A

Post History

71%
+3 −0
Q&A 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 --...

2 answers  ·  posted 5y ago by Monica Cellio‭  ·  last activity 2y ago by Mark Baker‭

#4: Post edited by user avatar Monica Cellio‭ · 2020-11-17T03:59:15Z (over 3 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 user avatar System‭ · 2019-12-08T11:33:51Z (over 4 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 by (deleted user) · 2019-12-08T11:33:51Z (over 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).

#1: Imported from external source by user avatar System‭ · 2019-03-29T02:32:37Z (almost 5 years ago)
Original score: 5