Walkthrough: Publishing Help Documentation

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

This topic shows how you create and publish a single content element to the Microsoft Dynamics AX Help server. A content element is a file or files that contain Help documentation for a specified topic. You publish a content element when you want to add custom documentation that appears in the Help viewer. The walkthrough includes the following tasks:

• How you use a template to create a content element.

• How you use the template to add the Help server document properties to a content element.

• How you use the template to produce the files that you publish to the Help server.

• How you add a folder to the file system of the Help server where you can put files.

• How you copy files to the Help server.

• How you view your content element in the Help viewer.

You will use the Microsoft Word template to create a content element. Typically, you use the Word template to create a simple content element that supplements an existing Help topic. The Word template is intended for people who are not comfortable working with HTML. For example, you use the controls in the Word ribbon when you want to add links, images, or tables to the documentation.

If your Help documentation requires links, illustrations, scripts, or styles, you might find the Word template does not provide enough flexibility to produce the documentation that you need. To produce more complex types of Help documentation or a content element that closely resembles existing Microsoft Dynamics AX Help documentation, you should use HTML. For information about how to create a content element that uses HTML, see Walkthrough: Creating Help Documentation.

Prerequisites

To complete this walkthrough, you must have the following:

• The Microsoft Dynamics AX client and Help viewer installed.

• Microsoft Office Word 2007 or a later version installed.

• You must log-in with an account that has permissions to add folders and files to the Help server file system. You might need a system administrator to give you access to the Help server file system.

Open the Word Template

This section describes how to find and open the Microsoft Word template. The template is installed on the Help server and can be accessed from the Help viewer. You use the template to create the files that you will publish to the Help server.

To find the Word template

1. Start the Microsoft Dynamics AX workspace, and then press F1. The Help viewer opens on your computer.

2. Enter Templates for Help Documentation into the search box and press Enter. The following illustration shows the search results.

   

3. Click the Templates for Help Documentation link in the list of search results. The specified topic opens in the Help viewer.

To open the template with Word

1. In the Help viewer, click the Dynamics Help Content Template.docm link in the list of templates. The file opens using Word.

   The following illustration shows the Dynamics Help Content Template.docm link in the Templates for Help Documentation topic.

   

2. You have to enable macros for the template. The macros will produce the files that you publish to the help server. If you do not enable the macros, you will have to manually create the required files.

   To enable macros, click the Developer tab, click Macro Security. The Word Trust Center window opens. In the Macro Settings list, click Enable all macros. Click OK.

3. Create a copy of the template file and save the copy to a location where you can work on your content element. The template you currently see in Word is the file from the Help server. You cannot save changes to that template file.

   To create a local copy of the template, click File, click Save As. The Save As window opens. Specify the location where you want to save the file. Click Desktop to save the file to your desktop.

4. In the Save As window, click File name: and type Contoso Help Test.docm.

5. Click Save as type:, click Word Macro-Enabled Document, and then click Save. The following illustration shows the Save As window.

   

6. After the Save As window closes, view your desktop and verify that the Contoso Help Test.docm file was created.

Add Help Content to the Template

This section describes how you use Word and the Contoso Help Test.docm template to create a content element. For more information about the Word and other templates that you can use, see How to: Create a Help Document using a Template.

The following procedures show how to add a title, section heading, and procedure to the template.

To specify the title for the content element

1. Update the title text at the top of the template. To change the title, highlight the default text of Using the Microsoft Dynamics Help Content Template for Microsoft Word, and then type Contoso Help Test.

2. To match the existing Microsoft Dynamics AX Help topics, use the controls in the Font group of the Word ribbon and specify the following values.

   Control name	Description
   Font	Segoe UI
   Font Size	16
   Font Color	Click the drop-down button, click More Colors, click the Custom tab, and then set Color model to RGB. In the individual color boxes, enter 0 for Red, 110 for Green, and 18 for Blue. Click OK.

   The following illustration shows how you can use the Colors window to specify the text color for the title. The specified color matches the title of existing Microsoft Dynamics AX Help documentation. However, you are not required to use the same colors or fonts.

   

3. Move the document cursor to after the horizontal line underneath the title, and then delete all of the existing text from the template.

To add an introduction to the content element

1. Specify the font to use for the introductory paragraph. To match the paragraphs in existing Microsoft Dynamics AX Help topics, use the controls in the Font group of the Word ribbon and specify the following values.

   Control name	Description
   Font	Segoe UI
   Font Size	10
   Font Color	Automatic

2. Type an introductory paragraph for the topic. Use the introduction to provide an overview of the information in the content element. The following illustration shows the introduction for the content element.

   

3. Press Enter to move to the next line.

To add a section heading to the content element

1. Specify the font to use for the section heading. To match the section headings of existing Microsoft Dynamics AX Help topics, use the controls in the Font group of the Word ribbon and specify the following values.

   Control name	Description
   Font	Segoe UI
   Font Size	14
   Font Color	Click the drop-down button, click More Colors, click the Custom tab, and then set Color model to RGB. In the individual color boxes enter 53 for Red, 90 for Green, and 136 for Blue. Click OK.

2. In the Home tab of the Word ribbon, set the Style to No Spacing and then type Adding a section to a Help topic.

3. On the next line, click Bottom Border from the Paragraph group, and then click Horizontal Line. A line is added underneath the section heading.

4. Right-click the horizontal line and then click Format Horizontal Line. The Format Horizontal Line window opens. Specify the following values:

   Parameter	Value
   Width	100%
   Measure in	Percent
   Height	1 pt
   Color	Click Use solid color (no shade). Use the color selection to specify the same color you use for the heading text.
   Alignment	Center

   The following illustration shows the Format Horizontal Line window.

   

5. Press Enter to move to the next line.

To add a paragraph to the section

1. Specify the font to use for the section body. To match the font that is used in existing Microsoft Dynamics AX Help topics, use the controls in the Font group of the Word ribbon and specify the following values.

   Control name	Description
   Font	Segoe UI
   Font Size	10
   Font Color	Automatic

2. In the Styles group of the ribbon, set the style to Normal.

3. Enter the text that you want to appear in the paragraph. Provide information about the procedure that is contained in the content element.

4. Press Enter to move to the next line.

To add a numbered list for the steps of a procedure

1. Click the Numbering button in the Paragraph group of the Word ribbon. A numbered list is started.

   To change the list style, click the arrow on the Numbering button. Use the Numbering Library to specify a style for the numbered list.

2. Type a description for the first step in the task.

3. Press Enter to add another numbered step. Type a description for that step. Repeat for each step that you want to add to the procedure.

   The following illustration shows a procedure that has four steps in a numbered list.

   

4. To end the list, click the Numbering button.

Add the Document Properties and Create the Files

This section describes how you use the template to populate the Microsoft Dynamics AX document properties for the content element. You use document properties to identify the content element and provide information that the Help server uses to match a content element to a request from the Help viewer. For more information about the document properties, see Authoring Help Documents.

This section also describes how you use the template to produce the files you will publish to the Help server. The Word template includes macros that generate the files for you. For more information, see Using Templates to Create Documentation.

To specify the document properties

1. Click the Microsoft Dynamics Help tab in the ribbon. The following illustration shows the tab in the Word ribbon.

   

2. In the Required Properties group, provide values for the following properties.

   Property	Value
   Title	Contoso Help Test
   TopicID	MyContosoHelpTest
   Language	English (United States)

   The following illustration shows the required document properties.

   

3. In the Optional Properties group, provide values for the following properties.

   Property	Value
   Publisher ID	Contoso
   Hide Publishers	Leave the text box empty.
   Keywords	Contoso;Test

   The following illustration shows the optional document properties.

   

To create files you can publish to the Help server

1. In the Save group, click the Automatically Save Properties and Save As Single File Webpage so that both boxes have a check mark. The following illustration shows the controls in the Save group of the Microsoft Dynamics Help tab.

   

2. Click File in the Word Ribbon, and then click Save.

3. Find the files you will publish to the Help server. View the location you specified for the Contoso Help Test.docm file. You should see that the macros in the template added the following files.

   File name	Description
   Contoso Help Test.htm	The file contains the document properties for the content element. The file redirects to the Contoso Help Text.mht file.
   Contoso Help Test.mht	The file contains the HTML that appears in the Help viewer.

4. After the file is saved, you can close Word.

Add Folders to the Help Server

This section shows how you add the folders to the Help server file system where you will publish your content element. You use folders to separate your Help documentation from the documentation provided by other publishers. You can also use folders to organize your content elements. For more information, see How to: Add Folders to the Help Server.

The following procedures add a publisher and a language folder where you will publish the two files for the content element files. If you have an existing folder on your Help server where you want to publish the files, you can continue to the next section.

To add a publisher folder to the Help server

1. Use Windows Explorer and open the Content folder of the Help server. The folder is typically found in c:\inetpub\wwwroot\DynamicsAX6HelpServer\Content of the Help server but can be changed during install.

2. Right-click the Content folder, click New, and then click Folder. A folder is added to Content. Right-click the new folder, click Rename, and then type Contoso for the folder name.

To add a language folder for the publisher

1. Right-click the Contoso folder, click New, and then click Folder. Right-click the new folder, click Rename, and then type EN-US for the folder name.

2. Double-click the EN-US folder. Leave open the Windows Explorer that shows the folder.

   The following illustration shows the Contoso\EN-US folders that you add to the Content folder of the Help server file system.

   

Publish Files to the Help Server

This section shows how you publish the .mht, and .htm files for the content element to the Help server. You publish the files when you want your Help documentation to be available to the Help viewer. For more information, see Publishing Overview.

If you want to keep the source file together with the .htm and .mht files, you can also put the .docm file on the Help server. However, you are not required to add the .docm file to the Help server.

Note

The steps to publish a content element are the same for both Word and HTML content elements. You can also follow this procedure to publish the file for an HTML content element.

To copy the files for the content element to the Help server

1. Open a second Windows Explorer window. Navigate to the desktop or the folder where you put the Contoso Help Test.mht, and Contoso Help Test.htm files.

2. Press Ctrl, and then click the Contoso Help Test.mht, and Contoso Help Test.htm files. Right-click a highlighted file, and then click Copy.

3. View the Windows Explorer window that you opened earlier when you added the Contoso\EN-US folders. Click the EN-US folder, right-click, and then click Paste. The Contoso Help Test.mht and Contoso Help Test.htm files are copied to the EN-US folder of the Help server.

   The following illustration shows the files added to the Contoso\EN-US folder of the Help server.

   

Next Steps

To view the content element in the Help viewer, press F1 from the Microsoft Dynamics AX client workspace. After the Help viewer opens, type Contoso Help Test into the search box, and then press Enter. In the search results, click Contoso Help Test. The topic appears in the Help viewer. The following illustration shows the content element in the Help viewer.