: Presenting documentation for a large software product My documentation team supports a massive software product, over 30 modules. These modules are individually licensed, so one customer might pay

Vote Up Vote Down

As another answer 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 was generated from Flare, and you can link to individual modules within the set 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.)

(0)

Vote Up Vote Down

The place where I work uses a home-brewed XML to HTML to CHM solution. We are reliant on the CHM's search engine (which frankly, is awful). We do not have a landing page, as much as a first page with a few generic links.

And yes, access to our help system is behind paywalls and often our clients do not have ready access to the internet; so the help system has to be completely local and not server-dependent. While never ideal, it is a necessity for our products and should not necessarily diminish your final product.

Having helped develop and work with a custom-built xml structure (we even have an XML programmer on staff), I strongly recommend against it. DITA provides a lot of interesting options and there are many good (and free) resources out there. Since there are far more options available to you than custom-built xml structures, I strongly suggest researching all the options before you settle on a structure.

I second the idea of a landing page with a really good search engine on the back-end. While it won't be used by customers after the initial exploration, it can greatly assist that first run through the documentation.

Video tutorials (embedded in the documentation or linked to it) are another great customer option. They've been very popular among consumers of our products.

Adobe Acrobat typically takes you to the word you're looking for and has done so for quite a few versions. If, however, your PDF generation process is turning everything to graphics instead of text, then making sure you're generating text is another way to improve the search in the PDF.

(0)