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 for all the modules where another might only pay to use a few of the modules.
Currently, most of our documentation is delivered via PDF and can be accessed via a dedicated website. However, given the complexity of the product, this poses many issues, most pressingly, it makes finding specific information hard. The site has a search functionality which does search within PDFs, but if you click through a link, you just get taken to the first page of the PDF. Also, this makes linking to other topics in a different PDF, almost impossible.
So, we're looking to move everything to HTML/XML based output. My manager would like us to give the customers a few different options to get their feedback on which they like best. However, it seems that for large products with many modules, it seems to me that there is a fairly standard layout, like these:
http://admhelp.saas.hpe.com/main/Content/AdmHelpCenter.htm http://qsupport.quantum.com/kb/flare/Content/doc_portal/Content/docs-portal/docs_portal.html
Basically, a landing page that lists out all the possible options, with links to module/product specific documentation centres.
Does anybody maintain, or maintained in the past, a documentation solution for a large software product that does not use this method? Is there an alternative that I'm missing?
Any suggestions, much appreciated.
This post was sourced from https://writers.stackexchange.com/q/27865. It is licensed under CC BY-SA 3.0.
3 answers
You are accessing this answer with a direct link, so it's being shown above all other answers regardless of its score. You can return to the normal view.
That approach is fine for a landing page. But what you have to bear in mind is that people don't use landing pages. This is true across all categories of information. There has been a steady decline in reader's use of landing page across all categories of information. Gerry McGovern charts the decline here: http://gerrymcgovern.com/the-continued-decline-of-the-homepage/
This does not mean you should not have a landing page. Their use has declined radically, but it has not been extinguished altogether. But it does mean that you can't rely on a landing page as the core of your navigational strategy.
The reason people don't use landing page anymore is that they have learned that it is easier to just search for what they want. Most of your users will start by searching Google (which is why putting your information behind a login is a bad idea). If they don't give up after the Google search fails, and log in to your site, they will go straight to the search bar and type the same query in there.
This is a problem, because your site search is much much worse at this stuff than Google. That is because search is a big data problem, and your sight search see several orders of magnitude less data than Google. So, it is not going to rank results as well as Google. That puts a lot of pressure on the topics that do turn up at the top of your search. If they are not the topics that the reader needs, they better provide links to those topics or the reader is not going to be able to find them.
Secondly, because the reader starts with a search, they arrive at an individual topic. Every page in your documentation set is a potential landing page, and every one of them needs to be written to work as one. This is a design principle I call Every Page is Page One, and I wrote a book about it: http://xmlpress.net/publications/eppo/
In an Every Page is Page One world, how you write the individual topics, and how you link them too each other, is more important than how you design the overall navigation. Overall navigation is still an important thing to think about, but it does nothing to solve the navigation problem for the typical users whose information seeking approach is to do a search, find something likely looking in the search results, and then follow links if they have to.
0 comment threads
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.
This post was sourced from https://writers.stackexchange.com/a/27871. It is licensed under CC BY-SA 3.0.
0 comment threads
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 comment threads
0 comment threads