CXO

Ten tips for helping your tech writer deliver good help

Even if you're lucky enough to have a technical writer on your team to assist in the development of your application's help system, you're still not off the hook. Here are 10 things you can do to help the tech writer help you.


A programmer can do plenty to facilitate development of help functions when a technical writer is on the team. Especially for larger projects, you may have a technical writer on your team to assist in the development of the help system. Here are 10 things you can do to make it easier for a technical writer to implement JavaHelp help systems that will enable end users get the most out of your applications.

JavaHelp-specific tips
  • Help determine the presentation of the helpset. The limiting factors in this decision are likely to be the available system resources and the amount of time the technical writer has to deliver the help system; unfortunately, this probably sets the limit for its usefulness too. Field-level context-sensitive help takes more space and more time to develop, but if the application is fairly complex, it may be important to include. A standalone help presentation can be delivered faster, but it won’t be as valuable.
  • Help develop and implement the ID strings for context-sensitive help so that your Java application properly invokes the help. Field-level help requires an ID string for each component. Secondary and pop-up windows will require your involvement as well.
  • Work on customization together. Advanced functionality can be added to the JavaHelp help set using Jcomponents. Most likely, that’ll be your job.
  • Determine how to deliver the help system. JavaHelp help systems can be delivered locally, on the user’s machine, or they can be server based. Factors to consider here are the resources of the server and/or the users’ machines and the help presentation complexity. Will you encapsulate the application?
  • Include the appropriate Java classes to implement JavaHelp support, including the JavaHelp JAR file jh.jar or jhall.jar. In Creating Effective JavaHelp, author Kevin Lewis suggests including in the installation program the ability to check the user’s site to see if the JavaHelp JAR has been installed. Here is a list of Java classes that must be included:
    —javax.help.TOCview
    —javax.help.JHelpTOCNavigator
    —javax.help.IndexView
    —javax.help.JhelpIndexNavigator
    —javax.help.SearchView
    —javax.help.JHelpSearchNavigator

General tips
  • Bring them in early. If it’s feasible, conduct the subject matter interviews together when gathering the business requirements for the application. Technical writers are typically adept at the user presentation side of development and may have questions to clarify issues at the beginning, which can prevent changes when the development process has already begun. And the sooner they understand how the application will work, the less explaining you’ll have to do.
  • Make yourself available. Be available to explain the application complexities when the technical writer has questions. Because online help requires a concise writing style that gets right to the point, the author should fully understand the functionality. And to achieve the goal of creating useful and usable documentation, the author needs to convey the right information to the defined audience. Give feedback to ensure that the author is developing topics that make sense for the application.
  • Be open to suggestion. Let the technical writer be your gauge for the usability of your application. Realize that if a seasoned technical writer has trouble explaining how to use a particular screen or field, it may be worth a second look at how that feature is presented. If an item can’t be explained clearly, you may need to revise its presentation into a more user-friendly format.
  • Communicate. Inform the technical writer of any code changes that affect the application presentation and require a change in the help content or display. Timelines usually dictate that the help system is authored simultaneously with the application, rather than when the application is complete. If the author can keep up with application modifications, you’ll decrease the possibility of delays in delivering the product.
  • Use a style guide. Save yourself time. Let the author develop a style guide (a good technical writing team already follows one, and it is most likely customized for your company) and the style sheets for your application. Follow the guidelines they set. Additionally, supply a guideline for naming conventions. You probably have standardized naming conventions for your application files.

Worth the effort
The JavaHelp download, available from Sun, includes examples and templates to make it easier to understand how to build professional help systems using Sun’s spec. If your technical writing staff uses a third-party tool to build help systems, it may provide support for JavaHelp, which further simplifies some of the more complicated aspects of developing help. At any rate, a well-designed help system makes your application easier to use and understand—and knowing how to assist the documentation staff will simplify your life in the long run.

Do you use JavaHelp?
Do you use JavaHelp to create help for your Java applications? What tips do you have for developers who use JavaHelp or work with technical writers? Send us an e-mail with your thoughts and experiences or post a comment below.

 

Editor's Picks

Free Newsletters, In your Inbox