Document IT solutions with custom Eclipse information centers, Part 1: Create your first information center

Recap and deliver your IT project experience for the benefit of clients, colleagues, and your own records. Quickly and productively document the solution you've implemented. Aggregate, organize, and share presentations, demos, product documentation, feeds, code samples, and other information you've created or reused for delivery in an Eclipse-based information center.

07 Sep 2012 - Per author comments, in section Start a custom solution information center, second sentence of first paragraph, updated link text and URL to point to the "Toolkit for Custom and Reusable Solution Information community" on developerWorks. In Resources > Get products and technologies, replaced the download URL for the "Toolkit for Custom and Reusable Solution Information" resource item.

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.



07 September 2012 (First published 05 January 2010)

Also available in Russian Japanese Portuguese

Overview

Implementing an IT solution involves integrating and customizing a variety of hardware and software components. The corresponding documentation and other technical information for compiling a "care and feeding guide" for the implemented solution can involve many authors, document locations, and document formats — ranging from traditional teamrooms and office documents to forums, blogs, and wikis. Gathering, organizing, and delivering the documentation to your client (or boss, or team) can be labor-intensive, especially if documentation is not your main expertise. The alternative is to provide inadequate documentation, which has its own drawbacks in the form of support costs, wasted productivity, and eroded client confidence.

This article introduces a toolkit that helps individuals or project teams expedite the task of documenting an IT solution. If jotting down a list of links or compiling a ZIP file of helpful documents is your usual approach to documenting an IT solution, consider spending a similar amount of time to seed a solution information center that can grow incrementally and gracefully over the solution's life cycle, incorporating technologies like RSS feeds to keep information fresh.

The toolkit encapsulates best practices for information design, architecture, and delivery into templates and automated routines, meaning it does not require skills in user experience, information development, or Eclipse plug-in coding. The toolkit is implemented in the Eclipse rich client platform, and produces standard Eclipse documentation plug-ins, but you do not have to install an Eclipse integrated development environment to use the toolkit.

Provide the client with a portable self-contained information center that can be viewed on a local or remote desktop, on an intranet, or on the Internet. As shown in Figure 1, the information center navigation, home page, and browser title can be customized for the specific solution.

Figure 1. Project Zero WebSphere sMash skill kit
Image shows Project Zero WebSphere sMash skill kit

If you deliver the solution information center and the project you used to create it, the recipient can extend the information center with more documentation throughout the solution life cycle. The toolkit for developing and updating custom solution information centers is available free of cost from IBM® alphaWorks.

The Toolkit for Custom and Reusable Solution Information, available from alphaWorks, helps you to build an information center for delivery to a client, or to share with your teammates. Starting a solution information project displays a graphical navigation tree into which you can drag and drop information, such as presentation files. Soon, you'll have the makings of a task-oriented solution information center without needing information development or user experience skills. You can export a self-contained information center for clients to run on a desktop, intranet, or Internet.

The toolkit enables you to:

  • Keep track of original and reused information to document your IT solution
    • Search for online content, capturing it for reuse
    • Accumulate your own personal content library: handy links, feeds, queries, and documents
    • Share content libraries with others by importing and exporting content
    • Reuse content in various custom information centers
  • Aggregate the information into well-organized solution information centers
    • Organize content in a best-of-breed navigation template
    • Create and share navigation view templates for your team
    • Customize the solution information center for a specific audience, such as one client
    • Put a unifying facade on a set of presentations, demos, and other information
    • Preview custom information centers easily and iteratively
  • Deliver custom solution information centers to clients and other audiences
    • Export ZIPs for delivery to clients
    • Run information centers on your desktop, supporting remote viewing by others
    • Host information centers on an intranet
    • Export solution information projects, enabling others to reuse and extend them

The Eclipse Platform includes its own help system based on XML table of contents that references HTML files, as described in Documenting your project using the Eclipse help system. The help system does not have to be integrated as part of a software user interface. In fact, the help system can be run stand-alone. It can be delivered once, then switched easily between desktop and intranet or internet hosting. These characteristics make the Eclipse help system a convenient vehicle for delivering a completely self-contained, self-sufficient documentation site (known as an information center).

The Toolkit for Custom and Reusable Solution Information makes the powerful Eclipse-based information delivery system more available to everyone, even if you're not a software developer or information Web-site developer. It provides a graphical drag-and-drop interface that enables you to produce Eclipse-based information centers containing your own choice of content, without any knowledge of the Eclipse plug-in packaging conventions.


Start a custom solution information center

Ready to create your first information center? To get started, obtain and install the Toolkit for Custom and Reusable Solution Information community on developerWorks. The toolkit is packaged as a ZIP file. Installing the toolkit is as simple as extracting the ZIP file contents. Next, open the toolkit and proceed to the workspace where you can start a solution information project.

To start a solution information project:

  1. Double-click the run.bat file to start the toolkit graphical interface.
    Figure 2. Double-click run.bat to start the toolkit
    Double-click run.bat to start the toolkit
  2. When the toolkit welcome screen is displayed, click the button for the Workbench, as shown in Figure 3. Note the availability of other buttons for reading an overview, finding tutorials, and more.
    Figure 3. Welcome screen with Workbench button selected
    Welcome screen with Workbench button selected
  3. Start a project, which corresponds to one solution information center.
    1. Select File > New > Solution information project from the menu. A new solution information project dialog will be displayed.
    2. Specify a project name, such as "Cloud computing solution for J.K. Enterprises."
    3. Click Finish.

A navigation view template is displayed you can customize and populate with content.


Customize the navigation view for your information center

The default navigation view template encapsulates best practices for documenting an IT solution in a comprehensive, well-organized way. However, as shown in the solution information center in Figure 1, you can change the default navigation view to suit your needs. For reasons described later, it is recommended that you avoid deleting sections of the default navigation view that might apply to your solution later, even days, months, or years later, as the solution evolves throughout its life cycle.

To customize the wording in the navigation view template for your specific project:

  1. Select a navigation template section (a yellow box), such as "My solution." It will turn bright yellow.
  2. Double-click the entry to activate editing of its label.
  3. Change the label wording, such as "Cloud computing solution for J.K. Enterprises." (The number 0 at the beginning of the navigation entry is displayed while you are editing the navigation view, but will not be displayed in your solution information center).
  4. To save your change to the current navigation entry, select a different navigation entry.
Figure 4. Customizing the navigation view
Partially customized navigation view

Experiment with dragging and dropping navigation sections to reorganize the navigation view. You also can add and delete navigation sections. The menu displayed when you right-click a navigation section provides a convenient way to customize the navigation view.


Gather the content you want to include

Consider the original and reused content you would like to gather and present in an integrated fashion in a single navigation view. Identify files, such as samples, multimedia, and office documents. Think about internal or external Web sites or wikis, or IBM Lotus Notes® databases with content to capture.

Content types supported by the toolkit

  • Files: Local documents, such as presentations, spreadsheets, demonstrations, and code samples
  • Web content: Web pages to which you either link or have the toolkit make local copies
  • Feeds: RSS and ATOM feeds to help your users find the latest content
  • Notes: Documents exported from Lotus Notes team rooms, or links to documents in Notes web interfaces
  • Books: Eclipse documentation plug-ins, which are reusable packaging units understood by information centers

After you notify the toolkit of a document or Web page for the first time, the document or Web page is available for use in multiple solution information projects. The toolkit supports many ways to collect content for your content library:

  • Search the IBM.com Web site for content and capture it
  • Import and export content libraries to share with other toolkit users
  • Import Eclipse help system plug-ins, the standard packaging for IBM product documentation
  • Import Lotus Notes views you have exported from Notes in XL format
  • Use configuration dialogs to add individual documents

Get started by using the configuration dialog to add a file from your local file system.

  1. Browse for the file (any file will do):
    1. Select Window > Show View > Files from the menu bar. The Files tabbed page is brought to the foreground, as shown in Figure 5. Note the other tabbed pages for adding other kinds of content.
      Figure 5. Adding files
      Adding files
    2. Click the Add Files button.
    3. In the Files Wizard, keep "default" as the group. Groups function like a set of drawers in which to sort and store your content.
    4. Specify a name to display in navigation, such as "Cloud computing overview" if that describes your file.
    5. Click Browse, then use the browsing dialog to locate the document on your file system.
    6. When you return to the Files Wizard, click Next.
  2. Specify information for the page that will introduce the file to users:
    1. Specify a title to display on an HTML page that the toolkit will generate to tell information center readers about your file.
    2. Specify a description to help users decide whether to view the file.
    3. Optionally, specify the publisher, which could be you, your company, the file's author, or any other value you like.
    4. Specify keywords that will be available to the information center search.
    5. Click Finish. You will see your file listed in the default group on the files tabbed page.

Customizing reused files

After you capture a file in the toolkit, you can edit it directly within the toolkit. Locate the file in the Files tabbed page. Right-click the file and select Edit with... to display the editor choices. The default editor typically is the editor defined in your Windows® operating system. When you save the file, you are saving the customized version for reuse in any of your solution information center projects.


Fill the navigation view with content

All of those tabbed pages in Figure 5 comprise your content library. You can drag and drop content, such as a file, into the navigation view from your content library.

To add your file to the navigation view:

  1. Make sure you are viewing the Files tabbed page.
  2. Make sure you are viewing files in the default content group.
  3. Locate your file in the default content group.
  4. Click your file. Drag and drop the file into the navigation view, where it is represented by a new navigation section.

For example, Figure 6 shows how a file called Product presentation looks when it is included in the Files tabbed page and when it has been dragged and dropped into the navigation view. Figure 6 also shows the use of a "sample project" group that has been populated with several files. (By the way, the Add Group button is just a few buttons away from the Add Files button you used earlier).

Figure 6. Adding content to the navigation view
Adding content to the navigation view

Customize the browser title and information center home page

The information center is displayed in a Web browser, whether the information center is run on the desktop, an intranet, or the Internet. The name of the information center is displayed in the title bar of the Web browser.

To customize information center name to be displayed in the browser title bar:

  1. Select Information Center > Browser Title from the toolkit's menu.
  2. Specify a browser title, such as "Cloud computing solution for J.K. Enterprises."
  3. Click the "X" on the Browser Title tabbed page to save your changes and exit.

The information center needs a home page to tell users about the solution. This is the first page displayed when users view the information center. The toolkit will generate a home page based on information you provide.

To customize the information center home page:

  1. Select Information Center > Home Page from the menu.
  2. Specify a page title, such as "Cloud computing solution for J.K. Enterprises."
  3. Specify various pieces of information, all of which are optional.
  4. Click the "X" on the Home Page tabbed page to save your changes and exit.
Figure 7. Providing information to generate a home page
Providing information to generate a home page

Figure 8 shows the generated home page corresponding to the information provided in Figure 7.

Figure 8. Previewing the generated home page
Previewing the generated home page

By the way, after you export the information center from the toolkit, the generated home page is included as an index.html file, along with a CSS file (welcome.css) enabling you to finetune the appearance of the home page. You can adjust the font styles, font sizes, background colors, etc.

An alternative approach to generating a home page is to import an HTML home page from your local system. The page must be named index.html. Select the Information Center > Home page menu option, but instead of filling out the template for generating a home page, click the radio button called Directory containing the index.html page, then follow the instructions.


Preview your information center

Invisible navigation blueprint

When you preview your solution information center, notice how your audience sees only the parts of the navigation view into which you've dragged and dropped content. The rest of the navigation view serves as an invisible blueprint or planning aid. You don't need to delete the unused parts.

You can start previewing your custom information center as soon as you drag and drop one piece of content, such as a file, into the navigation view. The information center navigation view will display only those parts you've populated with content. For this reason, it is advisable not to delete navigation sections that might be useful later, even if they are unused.

To preview your information center:

  1. Click Information Center > Preview on the menu bar.
  2. Wait for the information center to be displayed. View status in the Console area along the bottom of the toolkit.
  3. When the information center is displayed, try the navigation tree and search capabilities.
  4. Click the "X" on the Preview tabbed page when you're finished previewing.
Figure 9. Previewing the information center
Preview of information center within toolkit preview window

Notice from Figure 9 that the toolkit generates various HTML pages to display the information you provide about files and other content in your content library. The pages include a placeholder graphic (site.gif) you can swap with the graphic of your choice. For example, you can replace the arrow graphic next to Product presentation in Figure 9 with a company or project logo. Wait until you export the information center for delivery, then replace the graphic.

Troubleshooting tip: If the toolkit freezes or becomes non-responsive at any point, do not hesitate to shut it down using the "X" in the top right corner of the toolkit. Click OK to any resulting messages from the toolkit. The toolkit will return to normal behavior when you restart it. The freezing behavior is most common in association with previewing information centers.


Deliver your information center

Export the information center when you're ready to provide it to your audience. At any time, you can continue working on the solution information project and export subsequent snapshots of it.

To export the information center:

  1. Click Information Center > Export on the menu bar.
  2. In the resulting Package solution information dialog box, specify a destination for the exported information center. Click Finish.
  3. Continue using the toolkit for other activities while your information center is exported as a ZIP file.

Test your delivered information center

Test the steps that will be taken by the recipient of your solution information center

  1. Extract the solution information center from the *_package.zip file.
  2. Navigate to the directory containing the batch file for starting the information center, IC_start.bat.
  3. Send the IC_start.bat file to a text editor, such as Notepad.
  4. Optionally, check the -port argument, such as -port 8888. Adjust it to a different port, as needed.
  5. Close the IC_start.bat file. Double-click IC_start.bat to run it. A system command window is displayed to show the progress.
  6. Use a Web browser to view the information center.
    • (Optional) Test the information center on your own desktop by browsing: http://localhost:8888/help/index.jsp
    • Test remote viewing of the information center by browsing: http://your.host.name:8888/help/index.jsp

Double-click IC_end.bat and close your browser window when you want to shut down the information center.

Figure 10 shows an example of a solution information center in which a demonstration is running.

Figure 10. Example of an information center created with the toolkit
Example of an information center created with the toolkit

Conclusion

You just created your first information center. Use to toolkit to create a comprehensive information center, or start small by spending a few minutes to gather some documents into your toolkit for delivery in a presentable, lasting, and extensible form. How much you polish the information center's appearance or keep it as "a diamond in the rough" depends entirely on your business needs. Enjoy!

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. Select information in your profile (name, country/region, and company) is displayed to the public and will accompany any content you post. 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=460125
ArticleTitle=Document IT solutions with custom Eclipse information centers, Part 1: Create your first information center
publish-date=09072012