January 12, 2006

Formats Aplenty

As Ryan pointed out, the entire LabVIEW 8.0 Help is now posted on ni.com.

Because the LabVIEW Help .chm files are actually made up of individual HTML files, preparing those HTML files for the Web wasn't such a huge leap. Currently, the most challenging type of technical documentation to present on ni.com is printed or PDF content.

We make a PDF of every printed document that ships with an NI product and post the PDF at ni.com/manuals. But none of that content is searchable at ni.com. That's an awful lot of content to exclude from our site.

Google has a solution that works pretty well but there are also some big concerns with implementing something like it at ni.com. The biggest of which is that when you click an ni.com search result that happens to be a PDF, you then have to search for your terms again within the PDF. And some of these PDFs are quite large.

While one 300-page PDF might contain all your search terms, they don't necessarily appear on the same page or even in the same chapter. So exposing the PDFs through the ni.com search as is could lead you on a wild goose chase of clicking a link, waiting for a huge PDF to load, using the less-than-ideal PDF search feature to find each of your terms, realizing the document doesn't have what you need, and moving onto your next big PDF to repeat your search again. Not exactly the sort of user experience to instill trust in our technical documentation.

We've been investigating ways to convert the PDF content to HTML so we can display it in smaller individual documents, each of which would be indexed separately in the ni.com search. Even aside from the fact that we're starting from a not-so-flexible source format of Adobe Framemaker, this PDF content wasn't necessarily designed to be split up into smaller, disconnected chunks. Designing content for print/PDF is just fundamentally different than designing for online help.

The good thing is that all these problems are solvable, and we are pretty close to a good solution. A lot of folks point to the up-and-coming whippersnapper of the Format World as the solution to this problem—XML. But converting a Framemaker document to XML is no small feat, so it's hard to imagine a time in the near (or even distant) future when all NI printed/PDF documents will be sourced in the same format.

And who knows—by the time we've got most documents converted to XML, maybe a newer, better format will have emerged on the scene.

5 comments:

  1. I'm not even attempting to put the Sim Module PDF user manual online :-) We (the module tech writers) are having enough issues with our own non-PDF stuff ... but the good news is the FPGA Module help will be online soon.

    ReplyDelete
  2. Great post, Kelly. As the search business owner at NI, I get the "why don't you include PDFs in the search on ni.com" question all the time, from both employees and customers alike. You perfectly answered the reason why!

    ReplyDelete
  3. That's an interesting dilemma. Our manuals can be from two to one hundred pages long, so we don’t really have a problem with length, as you do. However, we don't have a site search, so you are still "one up" on us. :) I don't have any say in the design, so I grin and bear it. Luckily, it is a small site that's organized in a fairly simple way. Each department is responsible for the design of its own section, though, so nothing really matches past the first two pages. (sigh)

    Of course, while our manuals are shorter, they are not necessarily smaller (in MBs). We use a lot of high resolution photography, so we are constantly checking ourselves on file size. This is an issue because it inhibits clients on slower connections from opening our manuals in a timely manner. A site search including our manuals might help, but I don't think so. They are already intuitively organized by subject. If the client is looking for something that is not included in either manual for that product, they will need to call our service hotline. Doing a search of the manuals might keep the client from opening a large file for no reason, but it will also return many useless results, as well, and would probably still result in calling our service department.

    In the end, we have the same problem: the search terms might not be on the same page, producing false results, and still causing them to open a large file that does not actually contain the information they need. This is further complicated by the requirement that we must make each file "standard" quality and compatible back to Acrobat 4.0, which adds considerable size. The theory (I suppose) is that everyone has DSL or cable Internet access, but no one knows how to upgrade Acrobat; doesn’t it do that automatically when you have a constant connection?

    It will be interesting to see what kind of solution you guys find.

    ReplyDelete
  4. I think that consistency of documentation format is of awesome importance! I have experienced the lack of details info in the manual and general discussions in chm help... Because of different format the cross links seems to be impossible and that's bad.
    The most important thing is to have common source of documentation on LabVIEW itself at first.

    ReplyDelete
  5. Ivan, your comments echo other customer feedback we've received. We've tried to address the issue by moving most of our content to a single, searchable location--the LabVIEW Help. As of 8.0, it contains conceptual information about LabVIEW features, step-by-step instructions for using the features, and reference information for every palette object, VI Server object, dialog box, and so on.

    If you ever encounter a topic in the help or a part of a printed manual that doesn't give you the information you need, please let us know through the ni.com suggestion center so we can improve the content for all LabVIEW users.

    ReplyDelete