Post History

Source: https://writers.stackexchange.com/a/27872
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

As [another answer](https://writers.stackexchange.com/a/27869/1993) noted, landing pages are of limited utility -- you need them, but you shouldn't assume people will start there.

It sounds like your modules are all inter-related, even if one customer won't necessarily use all of them. (You mentioned linking between them, for example.) So another approach you can take is: one big HTML doc set, organized by component. This [example](https://my.vertica.com/docs/8.1.x/HTML/index.htm) was generated from Flare, and you can link to [individual](https://my.vertica.com/docs/8.1.x/HTML/index.htm#Authoring/HadoopIntegrationGuide/HadoopIntegrationGuide.htm) [modules](https://my.vertica.com/docs/8.1.x/HTML/index.htm#Authoring/ManagementConsole/UsingManagementConsole.htm) [within](https://my.vertica.com/docs/8.1.x/HTML/index.htm#Authoring/ExtendingVertica/ExtendingVertica.htm) [the](https://my.vertica.com/docs/8.1.x/HTML/index.htm#Authoring/KafkaIntegrationGuide/KafkaIntegrationGuide.htm) [set](https://my.vertica.com/docs/8.1.x/HTML/index.htm#Authoring/R-SDK/OverviewRSDK.htm) and still generate individual PDFs if you like. The benefit of the single HTML document set, as opposed to 30 different documents (HTML or otherwise), is that once you're in, you can easily see and navigate to anything else. That's a lot easier for the reader than having to go back to a landing page and choose a different module.

You might be concerned about the length of the list. How concerned you should be depends on the number of modules and how your readers access your documentation; more fits when using a browser on a full-size monitor than fits on a tablet, for instance. If you think you have too many modules to show on-screen in a single list like the TOC in the docs I linked, you have a few choices:

- Use scrolling. If you also put your most important or popular modules first, this isn't necessarily bad.

- If your modules fall into logical groups, add top-level categories to the TOC with the modules under them. As with the subtopics in the docs I linked to, expansion should be "in place" and durable. Over time much of the TOC might end up expanded and thus need scrolling, but that's ok because the user did it (and can undo it). But if your users won't be able to guess which of your few top-level topics is the right place to look, adding such groups might add more frustration than benefit.

- Support per-user customization. This won't help with people coming in from Google, but if you have user data, you can use it. If your documentation is behind a sign-in form (not a recommendation, but if you do...), you might know which modules that user is using -- so put those ones first. Or maybe you allow users to customize the view explicitly -- removing a module from the list makes it go away for that session. (Consider a "reset" link in that case so they can recover from errors.)

Original score: 1