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

50%
+0 −0
Q&A Structure for software documentation: long vs short pages

For online, developer-centered documentation for a complex software product, which structure is going to be more usable: a smaller number of long, comprehensive pages, or a larger number of more gr...

2 answers  ·  posted 6y ago by System‭  ·  last activity 5y ago by System‭

#3: Attribution notice added by user avatar System‭ · 2019-12-08T08:15:22Z (almost 5 years ago)
Source: https://writers.stackexchange.com/q/34131
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision by user avatar System‭ · 2019-12-08T08:15:22Z (almost 5 years ago)
For online, developer-centered documentation for a complex software product, which structure is going to be more usable: a smaller number of long, comprehensive pages, or a larger number of more granular pages? Which organization should I choose to make finding information easier and more user-friendly?

This is assuming each page is well-structured, has a sticky internal table of contents, and a page-wide search that can point the user to specific anchors inside the pages.

The arguments I see so far are:

- Granular pages can contain a single piece of information per page, can be easier to consume at a glance
- Comprehensive pages can contain all information related to a larger topic, or an overview of a whole feature
- Comprehensive pages are better for in-page/browser searching
- Granular pages make it easier to identify where one sub-topic ends and another begins
- Granular pages require more clicking to browse through content

* * *

Potentially related question: [What is considered an acceptable length for a technical document?](https://writing.stackexchange.com/questions/17892/what-is-considered-an-acceptable-length-for-a-technical-document)

#1: Imported from external source by user avatar System‭ · 2018-03-09T09:14:57Z (over 6 years ago)
Original score: 11