Post History
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...
#3: Attribution notice added
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
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)