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

[Guest]

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

[Guest]

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!

[Guest]

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

[Guest]

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.

[Guest]

Peter,

You sound like a go-to sort of guy for what my boss has tasked me to investigate. At one time, the 20 or so writers (worldwide) in my company all used unstructured FrameMaker. Long, long ago I used BookManager for a few years and went on to do bit with HTML and even with XML via RoboHelp and Eclipse. A new manager came on the stage in one of the writing groups, supposedly tasked with porting all of their documentation to HTML, and he chose to use Word and Drupal. My task is to be able to talk intelligently about how FrameMaker is better suited to work with Drupal (yes, structured FM is what we'd have to switch to) and I've about forgotten what little I learned about Drupal. The task I've assigned myself is to do whatever it takes to avoid having to give up FM for Word, lol.

We produce several types of books, but would likely start the process change for the User and Administrator Guides only. Both books extensively use variables and conditional text; the admin guide is about 300 pages while the user guides (one file, three books) are well under 100 pages. We currently maintain our documentation in Accurev--perhaps it's not the best doc control product out there, but it works for us.

Could you provide some guidance (or point me elsewhere to such guidance) about how FM integrates with Drupal? I know that at least a few of us are familiar with structured content but it would seem that we'll have a pretty steep learning curve no matter how we approach the issue.

Thanks very much for your reply!

Dimi Everette

[Guest]

Dimi,

First question to ask is "Can DUPAL do batch  importing (as in import this folder) of XHTML (and associated graphics/media files)?"

    ==> If yes, then sub questions.

Second question:  Does DRUPAL do automatic overwrites of previously loaded XHTML files?  This is important because a DITA => XHTML will regenerate a lot of content with identical filenames which then have to be replaced in the DRUPAL database.  However, this is a tricky question because I think DRUPAL can be used to track changes and cooperative editing.  If you are using this feature, then the question should be re-phrased to take that into account.  

    ==>  If yes you really don't need much else.  Just use the DITA-OT to dump XHTML (very reliable).  In a reasonable universe everything should be fine.  

Third question

Also visit this site:    http://www.ditainfo.info/  It is an implementation of a FrameMaker / DITA authoring system with publishing to DRUPAL.  

Other comments

Personally I would not trust MS-Word  to produce HTML for any commercial purpose unless your IT department can guanrantee a total lock down (no updates  without prior testing for impact on production) on every installation of MS-Word used in the production, and in some cases the feed-in to the production process.  MS Word is, IMH-but-experienced opinion, the most expensive authoring tool on the planet. 

The problem with  authouring tools like MS Word, even FrameMaker (but see note ** below), is that the SW provider can change the HTML output at anytime (but see note *** below).  Most likely this will happen a few hours before a major deadline.   I've wasted too much trying to get predictable results from MS Word in it's HTML output.  Things may have improved somewhat since the introduction of .docx, but not that I've seen -- though I have to admit I have not taken a very close look at it recently.

However, if the authoring system changes to be authouring of small chunks of information in many many many files extracted from a CMS, then MS Word might be able to handle that, especially if you can automate the imposition of an MS WORD styles sheet + automate post-HTML production clean up or the CMS and MS Word comes as a complete system.  But, if you do this then you may as well stick with DITA XML in FrameMaker or any one of the other DITA authouring tools (as long as they produce valid DITA XML) (see note * below) .   Doing that will 

1. reduce maintenance
2. reduce debugging cost
3. improve testability of the suite
4. improve predictability
5. improve production to XHTML
6. liberate you from vendor-specific authouring and production tools
7. and will be much cheaper in the long run.  

These benefits alll come from the fact that you are dealing with knowable inputs to production if you use DITA XML and a processing engine like the DITA-OT.  Yes, both get updated, but you do not have to accespt the update on the SW providers terms.  If you don't want to upgrade to the latest DITA or DITA-OT, then don't.  This is not true of MS Word and similar programs.  

Which leaves you with the problem of getting stuff into DRUPAL.  Check the link above for more info or go to one of the DRUPAL forums.   

Finally, you should test the idea of authouring in DITA and exporting to MS Word DOCX format.  oXygen I think has a default transform that does this.  Also FrameMaker 10 has a pretty good Save As Word function.   The oXygen DITA-OT transform will generate predictable stable MS Word.   The FrameMaker save As Word is subject to the same updating problem mentioned in relation to HTML. 

Hope that helps

*   "valid" is critically important.  Valid means that the structured and all required elements and attributes are present in a way that programs like DITA-OT have been designed to handle.   Any DITA file can be opened and edited in any good DITA authouring tool.  Valid is not "well formed".  Well formed wasa a concept floating around a while ago that tried to say each XML statement had a start and stop and was validly nested.  However, well formed does not require a pre-defined structure.  

**  I would not trust MS Word  or FrameMaker for HTML production because of the automatic update problem -- you cannot predict what the output will be after the update.  However, FrameMaker remains an excellent choice for authoring DITA (as are many other tools) because they should always save to valid DITA (otherwise it  whines and whines and whines ... a good thing).  This is almost true    but certainly in the case of FrameMaker, close enough for most purposes.  I have always been very impressed with FrameMaker's capability of inserting and using tool-specific XML code into a document without interfering with the validity of the DITA XML in the document.   It enhances the DITA authouring experience without sacrificing portability.    Therefore, since your production of XHTML will be from the DITA XML, not FrameMaker, you will find yourself in a very  safe, happy,  place. 

*** Rather than use MS Word to produce the XHTML, you could use the XML in the .docx files to produce the XHTML.  My company has done that (docx => DITA => XHTML) and it can work quite well if authours stick with certain styles.  This at least gets around the problem of trusting MS Word to produce the XHTML. 

[Guest]

That's very enlightening, Peter. Thanks very much!