Skip to main content
A
Anonymous
February 9, 2011
Question

What to Do Now That I've Got Structured Content?

  • February 9, 2011
  • 1 reply
  • 2921 views

Hello FrameMaker Gurus.

I've been working as a lone writer for a software company for many years. We have a 1300 page product manual that was originally authored in unstructured FrameMaker. We then use WebWorks to generate "Webhelp" that is both hosted online publically and installable with the software. You can see it here:

http://www.tableausoftware.com/currentonlinehelp

In preparation for multiple writers as well as multiple products, I have since converted the content to structured XML using the DITA DTD. I still author in Structured FrameMaker working from the XML files. I am now considering my options for how to generate the final output. My problem with webhelp templates is that the output is a framed help system connected by javascript links. That format makes it difficult to get the help pages to be indexed by search engines because they cannot get into the frames and if they do they cannot follow the javascript links. Further, webhelp output is isolated from our other UA content on the corporate website (e.g., knowledge base articles, forums, etc.). Our customers need to be able to search across all of these resources. The webhelp is a stand alone system with its own search. Additionally, we would like to have more cross linking into the help pages from other sources. The framed webhelp seems to make those deep dive links difficult. Finally, the look and feel of most webhelp (even with a fair amount of CSS/customization) is clunky at best. 1999 called, they want their help system back.

My thinking is that in order to get a help system that is easily indexable by search engines and integrates with our other content (managed by Drupal), I will have to generate unframed HTML pages that have the TOC built into the pages. Then I can either point a search appliance at it to unify Drupal content and help content in a single search or I can import the HTML into Drupal as part of my publish process. The HTML pages would be generated using the DITA open toolkit and custom XSLT stylesheets to do the transform.

Those pieces are outside of my technical skill level and would require a lot of time and money to put together. Before going down that route, I am trying to learn what other people do once they've gotten to an XML source using Structured FrameMaker. Does everyone just generate webhelp and be happy with it? If so, are they using DITA open toolkit or are they using other tools? How do they solve the search problems associated with webhep?

Any advice will be greatly appreciated. I don't want to dig down a hole of custom development to design the perfect help pages before I know that the solution is not already out there.

Thanks,

Erin

This topic has been closed for replies.

1 reply

A
Anonymous
February 9, 2011

I recommend you carefully separate your objectives.

Web access to your can be done by dumping your content to pure XHTML through the DITA-OT XHTML transform.  From there you can port it into DRUPAL if that makes sense. Not much customization required.

The help can continue to be delivered via Webhelp for the standalone product only

This may not be the decision you reach, but separating the objectives is critical.

One of the features of DITA is that compilation is cheap -- so you should be able to afford at least two outputs for two different purposes (except, in our experience, PDF -- we use FrameMaker for that because FOP is too expensive on the support development side).

Cheers!

A
Anonymous
February 10, 2011

Thanks for your response Peter!

I guess I'm trying to decide whether I have to import the content into Drupal. I'd actually prefer not to. However, using the XHTML output template in the DITA-OT doesn't get me help pages that have an integrated table of contents AND that are indexable by search engines. So to define my objectives they would be:

  1. Generate help pages to be published online (accessible to public) that search engines can index (e.g., Google, Yahoo!, Bing). These help pages must have some navigation affordance such as a table of contents.
  2. Provide a unified search box on our corporate website that will return results from both the above mentioned help content and Drupal content.
  3. Generate help pages to be installed locally for offline availability.

Given those three objectives, would you still recommend the DITA-OT for #1? If so, do I use custom XSLT to create unframed navigation or is there a built in template that gives me both navigation and allows search engines to crawl the content? Assuming I achieve #1, my understanding is that I would require a search appliance such as from Google to achieve #2 unless I was willing to slurp content into Drupal.

For number #3, you're right, I can use DITA-OT to continue to generate this as webhelp. However, I have not quite figured out how to get all of the webworks features into the DITA-OT output. Specifically, I only get a TOC. Is there a built-in search and index too?

Thanks again for your assistance.


Erin

A
Anonymous
February 11, 2011

Erin,

See comments below each of your points.  Before we get to those however I have a question about frames and search bots.  I believe that search bots (at their simplest) simpoly crawl through a directory structure looking for HTML files and index any they find.  Eclipse Help is also a frame based sytem and the search bots don't seem to have an issue with it.  Try this search in BING, Google and Yahoo:  "1.4.2 JRE, not included with the Eclipse SDK). On Windows, the executable"

The first hit in each set of results points to an HTML page in a frame.  So, you might want to clarify your objection to Frame-based web pages.

However, let's assume frames are a problem.  Then ....

==>  Generate help pages to be published online (accessible to public) that search engines can index (e.g., Google, Yahoo!, Bing). These help pages must have some navigation affordance such as a table of contents.

We are just about to do this ourselves -- every help page has it's own tailor-made unique ToC in a DIV that is placed on the screen using CSS.  Why? -- because we are expecting grief with the introduction of dozens of tablets with dozens of OS flavours in addition to the OSs we now support in browsers.  However, we are not there yet ... and we don't  know of any tool that does this automatically.    (The issue being that the ToC file can be very big with large suites -- at an average 3 topics per page, a 5000 page suite results in a 15,000 line ToC ... so it needs to be cut down)

==>  Provide a unified search box on our corporate website that will return results from both the above mentioned help content and Drupal content.

This could be messy and unnecessarily complex depending on the IT support you have.  Mixing a database source with a file-based source and then indexing them would not be my first choice unless you've seen it work.   I am not saying this is not a good solution, but it depends on the IT depth of your organization.  At a minimum you'll need Search Engine Friendly URLs on the DataBase side ... etc. etc.  I only metion this because you've said you are not an expert at these technologies.

==>  Generate help pages to be installed locally for offline availability.

See the comments at the top about frames and search ... you may not have to do anything differently for different HTML media. 

You may want to investigate Eclipse Help as an alternative.  It seems to be designed more narrowly around the task of delivering suites of information.

Further, if you are experienced and like using a tool already, like WebWorks or such, they will almost all accept raw HTML as input.  Modern ones accept DITA.  So, you could just use the DITA-OT to generate raw HTML and then generte your other outputs like WebHelp from there.

This has the advantage of leveraging your current expertise and ramining simple on the production side.  DIUTA-OT produces excellent XHTML ... really very very good.

Terms & ConditionsAccessibility statement
Using the community Terms of use Privacy Cookie preferences Do not sell or share my personal information ad choicesAdChoices