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.
The result: A custom information center
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
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 method: A toolkit with an easy graphical user interface
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 technology: Eclipse-based help systems
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:
- Double-click the run.bat file to start the toolkit graphical interface.
Figure 2. Double-click run.bat to start the toolkit
- 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
- Start a project, which corresponds to one solution information center.
- Select File > New > Solution information project from the menu. A new solution information project dialog will be displayed.
- Specify a project name, such as "Cloud computing solution for J.K. Enterprises."
- 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:
- Select a navigation template section (a yellow box), such as "My solution." It will turn bright yellow.
- Double-click the entry to activate editing of its label.
- 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).
- To save your change to the current navigation entry, select a different navigation entry.
Figure 4. Customizing the 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.
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.
- Browse for the file (any file will do):
- 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
- Click the Add Files button.
- In the Files Wizard, keep "default" as the group. Groups function like a set of drawers in which to sort and store your content.
- Specify a name to display in navigation, such as "Cloud computing overview" if that describes your file.
- Click Browse, then use the browsing dialog to locate the document on your file system.
- When you return to the Files Wizard, click Next.
- 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.
- Specify information for the page that will introduce the file to users:
- Specify a title to display on an HTML page that the toolkit will generate to tell information center readers about your file.
- Specify a description to help users decide whether to view the file.
- Optionally, specify the publisher, which could be you, your company, the file's author, or any other value you like.
- Specify keywords that will be available to the information center search.
- Click Finish. You will see your file listed in the default group on the files tabbed page.
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:
- Make sure you are viewing the Files tabbed page.
- Make sure you are viewing files in the default content group.
- Locate your file in the default content group.
- 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
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:
- Select Information Center > Browser Title from the toolkit's menu.
- Specify a browser title, such as "Cloud computing solution for J.K. Enterprises."
- 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:
- Select Information Center > Home Page from the menu.
- Specify a page title, such as "Cloud computing solution for J.K. Enterprises."
- Specify various pieces of information, all of which are optional.
- Click the "X" on the Home Page tabbed page to save your changes and exit.
Figure 7. 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
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
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:
- Click Information Center > Preview on the menu bar.
- Wait for the information center to be displayed. View status in the Console area along the bottom of the toolkit.
- When the information center is displayed, try the navigation tree and search capabilities.
- Click the "X" on the Preview tabbed page when you're finished previewing.
Figure 9. Previewing the information center
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:
- Click Information Center > Export on the menu bar.
- In the resulting Package solution information dialog box, specify a destination for the exported information center. Click Finish.
- 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
- Extract the solution information center from the *_package.zip file.
- Navigate to the directory containing the batch file for starting the information center, IC_start.bat.
- Send the IC_start.bat file to a text editor, such as Notepad.
- Optionally, check the -port argument, such as -port 8888. Adjust it to a different port, as needed.
- Close the IC_start.bat file. Double-click IC_start.bat to run it. A system command window is displayed to show the progress.
- 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
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!
- "Documenting your project using the Eclipse help system" introduces the Eclipse help system technology and describes how to develop plug-ins manually, rather than having the toolkit generate them for you.
- "Gain just-in-time skills with a developerWorks skill kit" describes and provides links to information centers produced with the toolkit to showcase developerWorks content about specific hot topics.
- Browse the technology bookstore for books on these and other technical topics.
- Check out the "Recommended Eclipse reading list."
- Browse all the Eclipse content on developerWorks.
- Follow developerWorks on Twitter.
- New to Eclipse? Read the developerWorks article "Get started with the Eclipse Platform" to learn its origin and architecture, and how to extend Eclipse with plug-ins.
- Expand your Eclipse skills by checking out IBM developerWorks' Eclipse project resources.
- To listen to interesting interviews and discussions for software developers, check out check out developerWorks podcasts.
- The My developerWorks community is an example of a successful general community that covers a wide variety of topics.
- Stay current with developerWorks' Technical events and webcasts.
- Watch and learn about IBM and open source technologies and product functions with the no-cost developerWorks On demand demos.
- Check out upcoming conferences, trade shows, webcasts, and other Events around the world that are of interest to IBM open source developers.
- Visit the developerWorks Open source zone for extensive how-to information, tools, and project updates to help you develop with open source technologies and use them with IBM's products, as well as our most popular articles and tutorials.
Get products and technologies
- Download the Toolkit for Custom and Reusable Solution Information.
- Check out the latest Eclipse technology downloads at IBM alphaWorks.
- Download Eclipse Platform and other projects from the Eclipse Foundation.
- Download IBM product evaluation versions or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
- Innovate your next open source development project with IBM trial software, available for download or on DVD.
- 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.