Accessibility
Icon or Spacer
   

Writing or Converting Help Sets for HomeSite Use

By Jeff Wilkinson
Web Developer
wilk4.com

One of the more useful features of the HomeSite editor (and its siblings CF Studio and JRun Studio) is that it has a system for built-in help and documentation that is very easy to customize and extend. Users can easily install their own sets of documents in HTML or text format that will be completely integrated into the editor's help system. Useful documents can include such things as W3C specs, references or tutorials on Web standards or techniques, or any set of HTML files that you find personally useful to have at hand when you're editing. This article will lay out some guidelines and suggestions for how to write help doc sets or convert existing sets for best use under HomeSite.

1. How the Integrated Help System Works

First off, the HomeSite help system has two parts, a help resource pane and the view of the page. The help resource pane gives the user a view of the available pages in a tree view format, allowing them to select what to view. The selected page is then shown in the editor's browse window using either the internal browser or the browser selected for internal browsing (generally Microsoft Internet Explorer, IE).

screenshot of help system

To find documentation, HomeSite's help system looks in subfolders in the Help folder of the HomeSite install directory. This is where users will be adding their own subfolders for additional help sets and documentation.

Example) c:\program files\homesite\help\My Help Set
screenshot of folders

The HTML title from each page is used as the page title in the help resource pane. Files in each set are shown sorted by that title. You can also create hyperlinks from within an HTML file to files with txt, dtd, and pdf extensions if you use Internet Explorer as the internal browser. Web graphics files (GIF, JPG, PNG) are viewable in Help files. The "Using HomeSite" manual has more information in Chapter 2: Exploring the Workspace -- Getting the Most from the Help System.

2. Getting Started

Now, basically, what you are putting together is a small, portable Web Site. The set of HTML docs should be ordered into a structured set of pages and linked together just as you would with any Web site. Useful pages like main index/home, table of contents (sitemap), and contact page provide some of the same structure that they would on a Web site.

  1. All images, style sheets, and other supplementary files need to be included in the set. Put them in subdirectories to keep them from being listed in the top folder.
  2. Portability is maintained by using relative linking between pages so that the set can be installed anywhere without breaking links. As long as you maintain the relative locations of the files and any subdirectories, they will work. Absolute linking should only be used for external references. Absolute linking between files in the set will almost always fail since editor install directories vary from user to user.
  3. If you are considering using Javascript or other code in your pages, you might consider that not all users will have IE set as the internal browser. Some may use the simple browser that comes with HomeSite and others may have different versions of IE. Normal cross-browser incompatibility design issues will apply. Try not to do things that will break if you can help it. Likewise, don't make your pages require server-side execution like cgi, ASP, or PHP. Few users will have a local Web server set up just for your docs.
  4. It might seem obvious, but before converting documentation created by someone else, make sure you have permission to do so, and to redistribute it. Just because it would be useful is not enough excuse to violate someone else's copyright. One example: There are nicely converted doc sets floating around for Microsoft's ASP docs. They are very helpful, but MS's copyrights do not allow that sort of conversion and redistribution without explicit permission. Even when you do have permission, make sure to include any original copyright information, credit, and links to the original source and its authors.

3. Organization

How you organize your files will depend a lot upon how many pages are in your set, what material you are covering, and so forth, but there are a few guidelines that can help make it more usable.

  1. Since a user sees the top folder first and most often, keep the number of files there fairly low, and put detail pages into subfolders named by category, section, or chapter.
  2. It's useful to have one main or index page at the top that is the 'home page' of the set. This might also include a table of contents or link to one as a starting point. This page should be obviously named and titled so users select it first.
  3. Files are displayed in the resource pane by HTML title, sorted alphabetically. This means that you should use descriptive titles, but keep them short. Don't put the set name in front of every title. "MySpecial Manual DocSet: Functions: FormatString" gets long and users may not even see the info they need at the end if your prefix is too long.
  4. You can control the listing order of your pages, chapters, or sections in the view by adding numbers or letters to the front. "1. Functions", "2. Language Reference", "3. Trouble-Shooting"
  5. Often detail pages will have links pointing up, previous, and next. This is particularly useful in a tutorial or reference that you might be reading through sequentially.
  6. Look at other help sets, both the sets included with HomeSite and those by other users, to see what things work and don't work. You'll get good ideas for how to structure and write your own set.

Here as an example is the converted PHP Reference Manual. Notice the subdirectories, few files at the top level, descriptive titles, and the linked table of contents.

screenshot of PHP Manual

4. Packaging and Testing

Once you have structured your help set and think it's almost ready to go, package it, then install it as a user would. Do further testing, link checking, and so forth on that installed set. It will give you the best idea of how other users will see it and let you work out bugs and usability issues better than if you were working on a set elsewhere.

  1. Package your whole set in a zip file, with subfolder paths saved in the zip.
  2. Add a readme.txt file at the top folder with the following info:
    • Your name, e-mail address, and/or Web contact info.
    • A stable download point address.
    • A description of what it is. (It's amazing how many people forget this.)
    • Version of the docs and date released. (If your set is a conversion of something else, the dates and revisions should cover both your conversion and the original source).
    • Copyright info and credits to you or the original sources.
    • Download or update URLs for the original sources.
    • Any install instructions needed.
    • Most of this info should also be in an HTML page linked into your set.
  3. Now, unzip it to a new subfolder of HomeSite/Help as if you were a new user and see how it works. Follow your own install instructions and see if they are correct and clear.
    • Do a link check on all files.
    • Run the HTML validator on all files.
    • Test the HomeSite Help search to make sure it works on your files.
    • Repackage any updates. Unzip and test again if necessary.
  4. Think about updates. Are you going to update the set or is it a one-time effort? If it is a conversion of some other source, will you track updates and reconvert, or update your set when the source changes?

5. Distribution

First rule: Don't be shy. If you have something useful, others will want to hear about it. Pass word around places where those interested in your subject hang out.

  1. Post it to your own Web site, the Developers Exchange, or other Web sites frequented by HomeSite users or those interested in the topic of your set.
  2. Post a mention of it in the HomeSite Support Forums and any subject-related forums.
  3. Notify Macromedia. They love to hear from users extending their tools and finding new ways to use them. They might even mention you in their Developer Newsletter or the HomeSite Developer Center.
  4. Notify other HomeSite-related sites so that they can list or link to you as well.
  5. Make sure your contact info and download addresses are easy to find in the set since people may get your set from almost anywhere and they may want to find you or check back for updates. Make sure you use contact info that you don't expect to change in the next few years. Add the info you might look for if you were downloading someone else's files.

Overall, try to think from a user's point of view. Use your docs, try lookups, install the set, and look for downloads as if you were the user, not the creator. If you can do this, your docs will be far easier to use and your users will appreciate your attention to their needs and to quality.

I hope this has given you some ideas for how to put together a useful, well-organized, and usable help set. Keep in mind that these guidelines don't only apply to writing help or documentation sets for HomeSite. Once you write a portable, downloadable help set, it can be turned into a Web site or used locally by anyone easily. If you want to see how useful that can be, check out DevGuru. They specialize in just that sort of thing and are recognized as a popular developer's resource site.

Jeff Wilkinson
ASP4HS: ASP Development Extensions for HomeSite
PHP4HS: PHP Development Extensions for HomeSite

 

Some of the Available Help and Documentation Sets

DevGuru Tutorials & Quick References W3C Specs DevEx and Misc Sets