Document IT solutions with custom Eclipse information centers, Part 3: Anticipating and managing change in reused content

In this third article in the "Document IT solutions with custom Eclipse information centers" series, understand the tradeoffs in content currency as you practice including links to content, copies of content, or both. Investigate techniques that will infuse new content into a solution information center after you deliver it to its audience. For example, you can provide a link that launches a search of another Web site's contents to find the latest documents, You can include RSS feeds that deliver updated content to keep your solution information center fresh.

Share:

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.



02 February 2010

Also available in Russian Japanese

Overview

Recall that the Toolkit for Custom and Reusable Solution Information supports collecting several types of content to publish in a custom solution information center. Content can include Web pages; local files like office documents; RSS, and ATOM feeds; exported Lotus Notes® documents; and Eclipse documentation plug-ins (known as "books" in the toolkit).

For some content types, you can include a copy of the content or link to the content where it resides, such as on a Web site or wiki. The following table summarizes which approaches are supported for each content type.

Type of contentCan include a link to itCan include a copy of it
Web pagesYesYes
Files (presentations, demonstrations, samples)NoYes
FeedsYesNo
Notes (exported Lotus Notes documents)NoYes
Books (Eclipse documentation plug-ins)NoYes

Including links to Web pages

Recall from earlier in this series that when you provide a link to a Web page, you configure a description of the page, such as its title, URL, abstract, and keywords. The description is used to generate an HTML page for your solution information center. The generated page provides the link to the Web page hosted elsewhere.

For example, Figure 1 shows a generated page that provides a link to the latest version of the Rational® Edge magazine. The secondary browser window shows what it looks like when the user clicks the link listed as the URL.

Figure 1. Linking to a Web page
Graphic shows linking to a Web page

The generated page is quite plain because the toolkit user took minimal time to provide a description of the Rational Edge. However, an advantage of linking to Web pages is that you can personalize the description to suit your information center audience. For example, if delivering the information center to a specific client, you can preface how the page to which you are linking pertains to the client's IT project.

Configuring a link to a Web page

Use the following instructions to include links to Web pages, so your information center always will reference the latest content on the Internet, or on your company's or client's intranet. Make sure that the recipients of your information center have access to the sites to which you are linking.

  1. Browse for an online Web page.
    1. Select Window > Show View > Web Pages from the menu bar. The Web Pages tabbed page is brought to the foreground.
    2. Click the Add Web Pages icon.
    3. In the Add Web Pages wizard, select a group for managing the content, such as Default.
    4. Specify a name to display in navigation, such as "IBM home page."
    5. Specify or browse to a URL, such as http://www.ibm.com.
    6. Ensure that Create link to page is selected.
    7. Click Next in the Add Web Pages wizard.
  2. Optionally, specify information for the page that will introduce the Web page to users.
    1. Specify a title to display on the page.
    2. Specify a description to help users decide whether to view the Web page.
    3. Specify publisher information.
    4. Specify keywords that will be available to the information center search.
    5. Click Finish.
  3. Locate the Web page in the toolkit and drag it into the navigation template.
    1. Return to the Web Pages tabbed page.
    2. Double-click the gray bar for the group to which you assigned the Web page.
    3. Locate the Web page by the title you gave it.
    4. Select the Web page.
    5. Drag and drop the Web page to a position in the navigation template.

Including copies of Web pages

When you provide a copy of a Web page, the page's contents are displayed directly in the content frame of your solution information center, as shown in Figure 2. When the user clicks a link on the page, the behavior depends on the depth you specified when you saved the page, as described in Part 2 of this series. If you captured the page at a single depth, links on the page will go to the live site from which you captured the page. At that point, the user will be navigating the Web site, rather than a copy of a page from the site.

Figure 2. Including a copy of a Web page
Figure 2 shows including a copy of a Web page

Configuring a copy of a Web page

Use the following instructions to save local copies of Web pages, which is a good approach when your information center needs to be used offline or when you want to preserve a snapshot of the content to guarantee that it will continue to match the specifications used in your IT solution.

  1. Browse for an online Web page for which to save a local copy.
    1. Select Window > Show View > Web Pages from the menu bar. The Web Pages tabbed page is brought to the foreground.
    2. Click the Add Web Pages button.
    3. In the Add Web Pages wizard, select a group for managing the content, such as Default.
    4. Specify a name to display in navigation, such as "IBM home page."
    5. Specify or browse to a URL, such as http://www.ibm.com.
    6. Select Download page content.
    7. Specify a depth, for example:
      • A depth of 1 saves this page, its graphics, and style information.
      • A depth of 2 saves this page and one layer of pages to which it links.
      • A depth of 3 saves this page, the layer of pages to which it links, and the pages to which those pages link.
    8. Click Finish in the Add Web Pages wizard.
  2. Locate the Web page in the toolkit and drag it into the navigation template.
    1. Return to the Web Pages tabbed page.
    2. Double-click the gray bar for the group to which you assigned the Web page.
    3. Locate the Web page by the title you gave it.
    4. Select the Web page.
    5. Drag and drop the Web page to a position in the navigation template.

Deciding whether to include links, copies, or both

If you're familiar with object-oriented programming, including a link to the content is similar to using "pass by reference" for a variable. You provide a pointer to the original content. Each time the user follows the pointer (the link) to the content, the user might find that the content has changed. Providing a copy of the content is similar to using "pass by value." The copy does not remain synchronized with changes to the original. However, relative to the original, the copy can be customized for the context in which you are using it.

The following table summarizes the tradeoffs for using links to content or copies of content. The options are not mutually exclusive. Suppose you include a copy of the content as a snapshot in time, particularly for content like a programming specification level. You might also include a link to the specification where it resides online, enabling users to access the latest version easily.

TradeoffsLinking to content elsewhereIncluding copies of content
Benefits
  • Sends user to the latest version of the content
  • Lets you provide a personalized introduction to the content
  • Captures a precise version of the content
  • Provides full-text indexing for information center search
  • Supports offline usage
Considerations
  • Does not necessarily match the version your user needs
  • Provides limited search indexing (title, abstract, keywords only)
  • Does not support offline usage
  • Risks the copy of content becoming outdated

Keeping your site fresh with RSS feeds

When you provide an RSS feed, your information center audience receives a list of links to Web pages or other online documents, as shown in Figure 3. The list is updated continually, based on the publishing activity on the Web site at which you subscribed to the feed. In this way, even if you deliver an information center to its recipient and never update it again, it is replenished with the latest content, including links to content that had not even been published at the time you delivered your solution information center.

Figure 3. Including an RSS feed
Figure 3 shows including a feed

Configuring an RSS feed

Perhaps the most difficult part of configuring a feed is determining the URL for the feed. (By the way, the URL for the feed shown in Figure 3 is http://www.redbooks.ibm.com/rss/rational.xml.)

Many Web sites that offer RSS feeds make configuring a feed quite simple. For example, IBM® developerWorks® offers a page that lists ready-made RSS feeds, including an introduction for those new to RSS feeds. If you click the link for a feed, such as the developerWorks home page, the feed is launched into a separate browser window from which you can capture the URL for the feed from the address bar of the browser.

After determining the URL, configuring a feed in the toolkit is much like configuring a Web page, except that you use the Feeds tabbed page.

  1. Select Window > Show View > Feeds from the menu.
  2. Click the Add RSS feeds icon on the Feeds tabbed page.
  3. Specify the group, name, and address for the feed, then click Next.
  4. Specify a title, author, and description for a page that will display the feed results.
  5. Click Finish.
  6. On the Feeds tabbed page, select the feed in the group to which you assigned it.
  7. Drag and drop the feed to a position in the navigation template.

Keeping your site fresh with queries

Maybe it's occurred to you that a link to a Web page does not have to be a link to one specific page but can be an http:// link that launches a search for multiple pages on a site. As shown in Figure 4 for example, you can configure a search of the IBM developerWorks library for tutorials. The search finds whatever tutorials are available at the moment that match the search criteria originally established in the Web page link.

Figure 4. Including a link that launches a search
Figure 4 shows including a link that launches a search

Configuring a search

Finding the URL that performs a search can be a bit trickier than finding the URL for an RSS feed. It's difficult to generalize because Web sites vary so much, but one approach is to perform the search directly on the site, then see if you can capture the resulting URL from the address bar. After determining the URL, configuring a search in the toolkit is the same as configuring any other Web page, as described previously. Figure 5 shows the configuration for Figure 4 in the toolkit.

Figure 5. Configuring a link that launches a search
Image depicts configuring a link that launches a search

Deciding among direct links, queries, and feeds

Linking directly to one pageProviding queriesProviding feeds
  • Provides the same result every time (a specific page)
  • Captures updates to a single page's content
  • Quality of results depends on how well the site maintains the single page
  • Provides a comprehensive set of results that can vary over time
  • Captures all pages that meet your search criteria, including newly added pages
  • Quality of results depends on how well the site classifies its pages for searchability
  • Provides only the very latest results
  • Captures new pages, based on the fact they are recently published (omits older pages)
  • Quality of results depends on the editorial judgment of the site providing the feed

Legal considerations

The toolkit provides an easy way to assemble a Web site of original and reused content for use on your desktop, company intranet, or the Internet. Always be cognizant of whether and how you are legally authorized to reuse and distribute content. Consult your legal counsel if you have any doubts about reusing content. Consult the terms of use for any Web sites from which you are capturing content, especially if you plan to redistribute the content to your clients. It's likely you'll need written permission from the content source if you are going to charge clients for content you are redistributing from another source.

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=465006
ArticleTitle=Document IT solutions with custom Eclipse information centers, Part 3: Anticipating and managing change in reused content
publish-date=02022010