Document IT solutions with custom Eclipse information centers, Part 2: Accelerate your ability to capture and reuse content

In this second article in the "Document IT solutions with custom Eclipse information centers series, master techniques for collecting and customizing reusable content for a solution information center that describes your IT project. Learn fast paths for capturing many documents at once for instant reuse.

Tricia York Garrett (yorkt@us.ibm.com), Information Architect, IBM

Tricia York GarrettTricia York Garrett is an information architect for the IBM WebSphere Application Server documentation team. She has been co-leading an internal workgroup to explore simple, scalable, and automated approaches for enabling individuals and teams to document their IT projects more easily and with higher quality. She gathered requirements from IT solution subject-matter experts to initiate development of the Toolkit for Custom and Reusable Solution Information.



19 January 2010

Also available in Russian Japanese

Overview

In Part 1, you created your first solution information center, containing a single file. Now that you understand the basics, you will learn techniques for accelerating the accumulation of documents in your content library, beginning with the import of a sample solution information project stocked with content.


Import content from another toolkit user

The first fast path for accumulating content is to import a solution information project created by another user. If anyone on your team captures content, everyone on your team benefits from reusing it. Importing a solution information project can add several documents of various types to your content library in one operation. The content is available for reuse in your new and existing solution information center projects. You also obtain the other user's solution navigation view, which you can reuse or disregard.

To practice importing a solution information project:

  1. Download the TKCARSI-SAMPLE.zip file from the Download section of this article.
  2. In the toolkit, select File > Import project from the menu bar. The Import Solution information project dialog is displayed.
  3. Browse to where you downloaded the sample solution information project, TKCARSI-SAMPLE.zip.
  4. When you return to the Import Solution information project dialog, click Finish. The toolkit will report that it is scanning the project.
  5. When the toolkit displays a dialog listing the content that will be included or overwritten, inspect the list, then click OK.
  6. Watch the progress bar. Typically, you can dismiss any error messages that are displayed.

As shown in Figure 1, after the project is imported, the toolkit will open its navigation tree. It is safe to close the navigation tree (File > Close project) if you do not want to work with the project right now. The content of the project has been added to your content library for use in any solution information project. The project you imported is now available from File > Open project.

Figure 1. Sample solution information project preview
Image showing Sample solution information project preview

Search for and capture IBM.com content

The second fast path for accumulating content is to use the toolkit's built-in IBM® Support Assistant search for finding and capturing content in bulk from the IBM Web site. You can capture copies of Web pages or links to the pages.

To populate your toolkit content library with content from IBM.com:

  1. Obtain a set of search results.
    1. In the toolkit menu bar, click Search > Search the Internet.
    2. When the Search Wizard dialog is displayed, choose your search targets. These are the parts of the IBM Web site that the toolkit will search for content. By default, all possible targets are selected. Choose fewer targets for a faster search. To practice, deselect all search targets except for IBM developerWorks.
      Figure 2. Search targets
      Image showing search targets
    3. In the search box, enter the terms you want to search for. Note the Advanced Search option, which lets you tailor your search for each target, such as limiting the search to a specific brand of IBM products. To practice searching, enter "cloud computing" (without quotation marks) as the search term.
      Figure 3. Search dialog
      Image showing search dialog
    4. Click the Go! button. Watch as the toolkit reports the Search Results.
  2. Select the search results that you might want to keep in your toolkit. In a subsequent step, you will formalize your choices.
    1. In the Search Results area, click a brand name, such as Information Management.
      Figure 4. Search results
      Image showing search results
    2. Browse the results, selecting the articles you want to capture for your solution information center. For practice, click Select All to capture the first 10 results.
      Figure 5. Search results selection
      Image showing search results selection
    3. When you are finished browsing and selecting results, click Next. The results you selected are displayed in the Save search results in content library page of the Search Wizard dialog.
  3. Narrow your selection to the search results that you definitely want to keep.
    1. In the Search Results Selected area, select a few search results you definitely want to keep. To select multiple results at one time, hold the Control button while you click each result.
      Figure 6. Search Results Selected area
      Image showing Search Results Selected area
    2. Optionally, in the Search Results to Save area, choose the content group in which you want to store the results you selected. Content groups are like little drawers for organizing your reusable content.
    3. When ready, click Add > to save the selected results in the selected content group.
      Figure 7. Search Results to Save area
      Image showing Search Results to Save area
  4. For the results you're keeping, decide whether to keep copies of the Web pages, or keep links to them.

    Use the radio buttons beneath the Search Results Selected area.

    • To keep links to the pages, click Create a link to the Web page.
    • To keep copies, select Download the Web page content and specify a page depth. For example:
      • A depth of 1 saves the page, including its graphics and style information.
      • A depth of 2 saves the page and one layer of pages to which it links.
      • A depth of 3 saves the page, the layer of pages to which it links, and the pages to which those pages link.
  5. Finalize the capture of the search results.
    1. Click Finish. The Retrieving Web Pages dialog will inform you of the progress.
    2. When the capture is finished, check the Web Pages tabbed page of your content library for the new pages. They are ready for you to drag and drop into the navigation tree of a solution information project.
      Figure 8. Search result is displayed in content library
      Image showing search result is displayed in content library
      Depending on the search target, the toolkit sometimes is able to capture details in addition to the Web page title and link. For example, if you click to edit the Web page properties, you will notice the description has been captured from the IBM developerWorks article, and the keywords field reflects your search terms.
      Figure 9. Search result details have been populated
      Image showing Search result details have been populated

Add plug-ins containing IBM product documentation

The third fast path for accumulating reusable content is to import an Eclipse documentation plug-in. An Eclipse documentation plug-in is a standard packaging format for displaying content in an Eclipse help system, such as an information center. When you obtain a plug-in, it is in an archive file, such as ZIP or TAR format. Plug-ins are available from many IBM product library pages, or sometimes are installed with the product help system. To locate documentation plug-ins, search the system for files or directories with the naming pattern "com.ibm.*.doc*" where * is a wildcard value.

The following procedure is based on the IBM WebSphere Help System plug-in: Virtual Enterprise (formerly Operations Optimization) plug-in, which you can download from the WebSphere Extended Deployment library.

To add the plug-in to your content library:

  1. Download a documentation plug-in from a Web site and extract the plug-in contents onto your file system.
  2. Browse for a documentation plug-in you downloaded or that was installed with a product.
    1. Select Window > Show View > Books from the menu bar. The Books tabbed page is brought to the foreground.
    2. Click the Add Books button to display the New Books wizard.
    3. In the New Books wizard, click the radio button called Directory: Browse to the plug-in's root directory.
    4. Click Browse, then navigate to the plug-in on your file system. This is a bit tricky: If there are nested com.ibm directories, select the innermost directory, as shown in Figure 10.
      Figure 10. Selecting the plug-in directory
      Image showing Selecting the plug-in directory
    5. When you return to the New Books wizard, double-check the settings based on Figure 11, then click OK.
      Figure 11. New Books wizard settings
      Image showing the New Books wizard settings
    6. Click Yes when asked, "Do you want to copy the content from the original directory into the toolkit?"
    7. Click OK if prompted with a dialog notifying you that some navigation files will be converted from their role as primary navigation files. This is just to say that any navigation views in the documentation plug-in are going to become subordinate to the main navigation view for your solution information project.
  3. Drag and drop navigation sections from the plug-in into your own navigation template.
    1. View the Books tabbed page in your toolkit.
    2. Click the appropriate content group to view the navigation files that are available inside this plug-in. In this case, the content group is named WebSphere® Virtual Enterprise Edition Version 6.1, and the navigation files have names such as prodovr.xml.
      Figure 12. Plug-in content added to content library
      Image showing the plug-in content added to the content library
    3. Drag and drop some or all of the navigation files to positions in the navigation template.
      Figure 13. Plug-in content included in solution navigation view
      Image showing the plug-in content included in the solution navigation view
  4. Preview the information center to see and adjust the results.
    Figure 14. Plug-in content displayed in information center
    Image showing the plug-in content displayed in the information center

Documentation displayed in many online IBM information centers and for some Eclipse-based open source projects is packaged in the form of Eclipse documentation plug-ins. If IBM product library pages do not offer the plug-ins you seek for download, contact IBM to help identify the need for the downloads.


Automatically merge plug-in content

Best practice: Automatic Merge Links

If you suspect that the Automatic Merge Links feature depends on the default navigation provided when you start a new solution information project, you're right.

  • Adding new navigation sections doesn't hurt the ability to merge content later.
  • Rearranging sections doesn't stop the merge from finding the sections in their new locations.
  • Deleting sections will remove their capability to receive merged content.
  • Renaming a section while keeping its original meaning doesn't hurt, such as changing "Troubleshooting" to "Problem determination."
  • Repurposing a section, such as renaming "Developing business applications" to "Implementing SOA governance," is likely to produce odd results if you merge content into the navigation later. Instead, create new navigation sections, as needed.

After you add a documentation plug-in to your toolkit, you must drag its content into the navigation of your solution information project. What if you could use a single toolbar button to tell the toolkit to disperse the plug-in's content to appropriate locations throughout your solution navigation? You can, if the plug-in has been enabled for the Automatic Merge Links feature. This article includes a TKCARSI-TEMPLATE.zip file you can use to try the Automatic Merge Links feature, as well as a specification and reference implementation for plug-in authors seeking to enable their plug-ins.

To try the Automatic Merge Links feature:

  1. Obtain the com.ibm.soln.TEMPLATE.enabled.doc_1.0.0 plug-in.
    1. Download the TKCARSI-TEMPLATE.zip file from the Download section.
    2. Extract the contents, so you have a directory named com.ibm.soln.TEMPLATE.enabled.doc_1.0.0.
  2. Add the documentation plug-in to your toolkit.
    1. In the toolkit, select Window > Show View > Books from the menu bar. The Books tabbed page is brought to the foreground.
    2. Click the Add Books button to display the New Books wizard.
    3. In the New Books wizard, click the radio button called Directory: Browse to the plug-in's root directory.
    4. Click Browse, then navigate to the com.ibm.soln.TEMPLATE.enabled.doc_1.0.0 folder on your file system.
    5. When you return to the New Books wizard, click OK.
    6. Click Yes when asked, "Do you want to copy the content from the original directory into the toolkit?"
  3. Create a new solution information project, or open an existing one. It is recommended that you create a new project for this demonstration, especially if you have deleted or modified sections in the default navigation of your solution information project. If you are previewing a solution information project, shut down the preview before performing Automatic Merge Links on the project.
  4. Click the Automatic Merge Links button. Figure 15 highlights its location. The button becomes active when you have a solution information project navigation tree open and you have selected a Book (documentation plug-in) enabled for the Automatic Merge Links feature. Otherwise, the Automatic Merge Links button remains grayed out.
    Figure 15. Location of Automatic Merge Links button
    Image showing the location of the Automatic Merge Links button
  5. Confirm and watch the merge operation. Click Yes when prompted for confirmation. The toolkit will report how many navigation sections are being populated with content from the plug-in. For the TKCARSI-TEMPLATE plug-in, about 100 navigation sections receive one or more documents from the plug-in. To see the results, expand the navigation tree of your solution information project.
    Figure 16. Template content merged into navigation tree
    Image showing the template content merged into the navigation tree
  6. Preview the information center to further explore the results, as shown in Figure 17. In particular, notice how one navigation section can receive multiple documents from the content plug-in. For example, three navigation entries have been added to the section Demonstrate the template > Solution overview > Business context > Overview.
    Figure 17. Template content displayed in preview
    Image showing the template content displayed in preview

To enable a documentation plug-in for the Automatic Merge Links feature, the author of the plug-in adds special comment lines to the plug-in. The TKCARSI-TEMPLATE.zip file provides a specification and a reference implementation for plug-in authors.

You can view the special comment lines inside the TKCARSI-TEMPLATE.zip plug-in.

  1. If you added the plug-in to your toolkit, navigate to the directory: tkcarsi1.5\bigeasy\workspace\content\com.ibm.soln.TEMPLATE.enabled.doc_1.0.0. Otherwise, navigate to the location on your file system where you downloaded and extracted the plug-in contents. The directory contains the XML files that define the navigation entries for the documents available within the plug-in. The TKCARSI-TEMPLATE.zip plug-in provides an XML file corresponding to each location in the default navigation displayed by the toolkit when you start a new solution information project.
  2. View the Soln_Business_context_OVERVIEW.xml file in a text editor. Note the second line, which begins with <--Target=. In each XML file, you'll find a similar case-sensitive target statement that specifies where the content belongs in the navigation of a solution information project. As long as the comment is present, the name of the XML file doesn't matter.
Listing 1. Soln_Business_context_OVERVIEW.xml file
<?xml version="1.0" encoding="utf-8"?>
<!-- Target=Soln_Business_context_OVERVIEW -->
<!--Arbortext, Inc., 1988-2005, v.4002-->
<?APT Element gi="toc" attrs="label topic link_to"?>
<?APT Element gi="topic" attrs="label href"?>
<?APT Element gi="anchor" empty="yes" attrs="id"?>
<?NLS TYPE="org.eclipse.help.toc"?><!--Nav fragment example-->

<toc label="This will not show" topic="This will not show">
<topic label="BUSINESS CONTEXT OVERVIEW" href="topics/Business context overview.html">
</topic>
<topic label="VALUE PROPOSITION" href="topics/Value-proposition.html">
</topic>
<topic label="WHO BENEFITS FROM THIS SOLUTION" href="topics/Who-benefits.html">
</topic>
</toc>

Import views from IBM Lotus Notes databases

The fourth and final fast path to accumulating content is to import a set of IBM Lotus Notes® documents in Domino® XML format (DXL). You can export an entire set of documents from a view in a Lotus Notes database, such as a specific folder in your mail database. You can import the entire set for reuse in your solution information centers. Note the limitation that the toolkit imports the content of Lotus Notes documents, but it does not import their attachments.

To import a set of Lotus Notes documents into the toolkit:

  1. Browse for a local DXL file containing some exported Lotus Notes documents.
    1. Select Window > Show View > Notes from the menu bar. The Notes tabbed page is brought to the foreground.
    2. Click the Add Lotus Notes content icon (picture of icon).
    3. In the Notes Content wizard, select a group for managing the content, such as default.
    4. Select From DXL.
    5. Specify a name to display in navigation, such as "Identity management project plan."
    6. Click Browse, then navigate to the Notes document's online address.
    7. Click OK to close the file-browsing dialog.
    8. Click Next when you return to the Notes Content wizard.
  2. Locate the Notes document set in the toolkit and drag it into the navigation template.
    1. Return to the Notes tabbed page.
    2. Double-click the gray bar for the group to which you assigned the documents.
    3. Locate the set of Notes documents by the title you gave the set of documents.
    4. Select the documents.
    5. Drag and drop the documents to a position in the navigation template.

It's beyond the scope of this article to describe how to write a LotusScript routine that exports a Notes documents in DXL file format, but reference information about Lotus Notes programming and the DXL format is available on the Internet. For those already familiar with Lotus Notes programming, here's an overview of a tested approach for exporting a set of documents:

  1. Replicate your Notes database locally, if that is the only place you have permission to create a new view.
  2. Select Create > View from the menu bar in Lotus Notes. Specify a SELECT statement to define which documents are displayed the view.
  3. Select Save and Customize, which opens the Lotus Notes programmer's pane.
  4. In the programmer's pane, select Create > Action and configure a new ExportDXL action.
  5. Edit the ExportDXL action to include a LotusScript that exports the documents in the view to a .dxl file at a specified location on your system.
  6. Save the action and exit the programmer's pane.
  7. Look for your new view, which includes an ExportDXL button at the top.
  8. Test your LotusScript by clicking the ExportDXL button, then checking the directory where you expect to find your .dxl file.

Conclusion

You learned four techniques for accumulating reusable content for documenting your IT solution with a solution information center produced with the Toolkit for Custom and Reusable Solution Information. Of course, as soon as you capture content, you risk it becoming outdated. The next article in this "Document IT solutions with custom Eclipse information centers" series will describe how to manage change in your reused content.


Downloads

DescriptionNameSize
Documentation plug-in templateos-eclipse-infocenter2-TKCARSI-TEMPLATE.zip266KB
Solution information project sampleos-eclipse-infocenter2-TKCARSI-SAMPLE.zip11,000KB

Resources

Learn

Get products and technologies

Discuss

  • The Eclipse Platform newsgroups should be your first stop to discuss questions regarding Eclipse. (Selecting this will launch your default Usenet news reader application and open eclipse.platform.)
  • The Eclipse newsgroups has many resources for people interested in using and extending Eclipse.
  • Participate in developerWorks blogs and get involved in the developerWorks community.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=461252
ArticleTitle=Document IT solutions with custom Eclipse information centers, Part 2: Accelerate your ability to capture and reuse content
publish-date=01192010