Documenting Websites

The power of TechWriter comes from its ability to leverage information from your website. In this topic we will show you how to document websites by including comments directly within the files that make up your site as an alternative to creating annotations within TechWriter.

Some important things to consider when deciding whether or not to embed comments directly within your files are:

How the increase in file size will affect the performance of your website. Each comment you embed adds to the overall size of the file that must be transferred down to the user's web browser in order to be displayed. If you need a website that is highly responsive even over slow connections, you may need to use TechWriter annotations in order to keep your files lean and mean.
Whether or not you want other users to see your comments. If your comments are strictly for internal use, and you want to make sure a user of the website would not be able to discover them, use TechWriter annotations instead.

Documenting Pages

TechWriter supports two different methods for creating comments for pages. One method that can be used is to add a Description META tag to each page. The syntax of the META tag is as follows:

<meta name="DESCRIPTION" content="<comments>" />

where <comments> is the text of the comment you want to create. This method is appropriate when all you need is simple descriptions for your pages. This method should not be used if you wish to include comment tags for additional formatting as those tags would not be properly recognized by search engines that use the META tag contents for displaying results.

The other method is to add an XML tag to the page. The syntax of the XML tag is as follows:

<xml id="comments">
<comments>
</xml>

where the id attribute is always set to "comments" and <comments> is the text of the comment you want to create. This method should be used if you plan to include comment tags in your comments or you simply want to maintain descriptions that separate from what a search engine would see.

Documenting Images

TechWriter supports two different methods for creating comments for images. One method is to use IPTC or EXIF meta data to set the comment right within the image file. The easiest way to do that is to use Windows Explorer to display the Summary tab of the Properties dialog for the image file. If the image supports meta data, a Comments property should be available for you to edit. The only web-friendly image format that currently supports meta data is JPEG. For all other image formats, such as GIF and PNG, a different method must be used.

TechWriter can also use the contents of the ALT attribute of the IMG tag as the comments for the image that is being referenced as shown below.

<img src="images/adivo3.jpg" alt="The company logo for Adivo" />

While this method will work with any type of image there are a couple of limitations to be aware of. First, you must consistently include the same comment on every IMG tag that references the same image to ensure that TechWriter finds the correct comment. Second, the text of the ALT attribute must not include any comment tags as those tags may not be properly recognized by web browsers and page readers.

Documenting Embedded Media

TechWriter supports the use of the TITLE attribute of EMBED, OBJECT and APPLET tags as the comments for the embedded media that is being referenced as shown below.

<embed src="player.swf" width="400" height="300" title="A short introductory video about our products." />

This method for specifying comments has a couple of limitations to be aware of. First, you must consistently include the same comment on every tag that references the same embedded media to ensure that TechWriter finds the correct comment. Second, the text of the TITLE attribute must not include any comment tags as those tags may not be properly recognized by web browsers and page readers.

Documenting Style Sheets and Scripts

TechWriter will look at the very top of each CSS style sheet and Javascript file for a comment block to use as the comment for the file. CSS style sheets and Javascript files use /* and */ to begin and end comment blocks as shown in the following example:

/* Enterprise Standard Styles */

TechWriter also supports the use of line comments in Javascript files that are prefixed with two slash characters (//). Comments for scripting languages other than Javascript are not currently supported.