Templates for Help Documentation

  • Article

Applies To: Microsoft Dynamics AX 2012 R3, Microsoft Dynamics AX 2012 R2, Microsoft Dynamics AX 2012 Feature Pack, Microsoft Dynamics AX 2012

The Microsoft Dynamics AX Help system includes templates that you can use to create documentation files. You can then publish these documentation files to the local Help server. The templates include sections, styles, and guidelines, and they represent the most frequently used types of Help documentation. The templates are stored on the local Help server.

  • The Microsoft Word template helps you use Word to create Help documentation. You can also convert existing documentation to a format that you can publish to the Help server.

  • The HTML templates help you create documentation that uses the same formats and styles as the Help documentation from Microsoft. To use the HTML templates, you must have an HTML editor or a text editor, and you must be comfortable with editing HTML.

The following sections describe how to use each type of template.

The Microsoft Word template

The Microsoft Word template helps you create Help documentation by using Microsoft Word 2007 or Word 2010.

  • By default, the template creates or updates an .mht file every time that you save the file. Your content element does not appear in your Help viewer until you publish the .mht file to the local Help server.

  • If you do not use the .mht file, you can publish a Word .docm or .docx file. However, the Help viewer cannot open .docm and .docx files. Therefore, if you do not want to use .mht files, each client computer must have Microsoft Word or another program that can open .docm or .docx files.

To publish a content element, you must include several document properties, so that the Help server can match the content element to a Help request. For a content element in a Word file, you also publish an HTML file that includes the required document properties. You can use the Word template to automatically create the HTML file.

To open the Word template on your computer, verify that you have Word 2007 or Word 2010 installed, and then click the link in the following table.

File name

Description

Dynamics Help Content Template.docm

Use the Word template to create new documentation. You can also copy documentation from an existing file, and then paste it into the template.

Use the Word template

  1. When you open the template, enable macros. If macros are not enabled, you cannot use the template to produce the supplemental HTML file that the Help server requires.

  2. Click Save As, and then specify a name and location for the file. Use .docm as the file type.

  3. Add the title, headings, and other Help information to the template.

  4. Click the Dynamics Help tab, and then enter the required document properties. If you do not populate every property that is required, you cannot retrieve your documentation from the Help server. The instructions in the template describe how to populate the required and optional properties.

  5. Select the Automatically Save Properties check box, if it is not selected. When the check box is selected, the template automatically updates the HTML file every time that you save the document.

  6. Select the Save as Webpage check box, if it is not selected. When the check box is selected, the template automatically creates or updates an .mht file every time that you save the document.

  7. Save the file. When you save the file, the .docm, .mht, and .htm files are automatically created or updated by using the name and location that you specified.

  8. To publish a document, copy both the .mht file and the .htm file to a subfolder of the c:/inetpub/wwwroot/<HelpServerName>/content folder on the Help server. Typically, the name of the subfolder provides the name of the publisher. For example, the following subfolder contains Help documentation that is supplied by Contoso:

    c:/inetpub/wwwroot/<HelpServerName>/content/Contoso

    Note

    If you want the document to be opened in Word, publish the .docm or .docx file instead of the .mht file. You must publish the .htm file to the same folder as the .docm or .docx file.

    To publish a document, you must have permission to add files to the specified subfolder. Ask the system administrator of your Help server to grant your logon permission to add files to that subfolder.

The HTML templates

The HTML templates help you create documentation that resembles Microsoft Help documentation. To use an HTML template, you must have an HTML editor or a text editor. The editor must be able to save your documentation as an .htm or .html file. In addition, you must know how to modify individual HTML elements and attributes.

To view an HTML template, click a link in the following table.

File name

Description

Dynamics Help Concept Template.htm

Use this template to create an overview of a subject area. This template has the fewest elements and provides the greatest flexibility.

Dynamics Help Form Template.htm

Use this template to create documentation for a form. This template helps you organize your documentation around the components and controls that the form contains.

Dynamics Help KeyTask Template.htm

Use this template to create documentation for a complex task. This template helps you organize your documentation around the steps and resources that you use to complete the task.

Dynamics Help Orientation Template.htm

Use this template to create documentation that contains links to related documentation. This template helps you introduce a subject area and provide links to related documentation.

Dynamics Help Procedure Template.htm

Use this template to create documentation for a simple task. This template helps you organize your documentation into a series of numbered steps.

Use an HTML template

  1. To create a file from a template, right-click the link for the template in the previous table, and then click Save Target As. In the Save As dialog box, specify a name and location for the file. Use .htm or .html as the file type.

  2. In your HTML editor or text editor, open the file that you created.

    Note

    When you open the file, the format and style may differ from the format and style that you see in the Help viewer. Formats and styles are supplied by links to .css files that are located on the Help server.

  3. Use the editor to add the title, headings, and other Help information to the template. Each template includes HTML comments that describe how to complete that template.

  4. Find the HTML meta elements that contain the document properties. Specify a value for the content attribute of each element. You must specify values for the required document properties, such as language, Title, Microsoft.Help.Id, and Microsoft.Help.F1. You can also specify values for the optional document properties, such as publisher, Microsoft.Help.Keywords, and suppressedPublishers. HTML comments in each template describe how to populate the document properties.

  5. Verify that the href attribute of the each link element correctly specifies the location of a .css file on your Help server. The .css files are typically located in the following folder:

    c:/inetpub/wwwroot/<HelpServerName>/content/Microsoft/en-us/local

    The href attributes of the link elements in each template specify the following default paths:

    ../local/AX.css

    ../local/presentation.css

    To use the .css files for your topic, you must update the href attribute of each link element. An href attribute must specify the full path from the folder where you publish the .htm file to the .css file. For example, you publish your .htm file to a folder named Contoso/en-us/ in the content folder on the Help server. You then update the href attributes of the link elements, so that they specify the following paths:

    ../../Microsoft/en-us/local/AX.css

    ../../Microsoft/en-us/local/presentation.css

  6. Save the .htm or .html file. Use the name and location that you specified. To change the file name, click Save As, and then type a new name for the file.

  7. To publish a document, copy the .htm or .html file to a folder on the Help server. Typically, the content folder is installed on the Help server at a location such as c:/inetpub/wwwroot/<HelpServerName>/content. Typically, the name of the subfolder provides the name of the publisher. For example, the following subfolder contains Help documentation that is supplied by Contoso:

    c:/inetpub/wwwroot/<HelpServerName>/content/Contoso

    To publish a document, you must have permission to add files to the specified subfolder. Ask the system administrator of your Help server to grant your logon permission to add files to that subfolder.

See also

Writing Documentation for the Help System

Customizing the Help System

Publishing Overview

Announcements: To see known issues and recent fixes, use Issue search in Microsoft Dynamics Lifecycle Services (LCS).