Content Development Reference. Including resources for publishing content on the Help Server

Transcription

1 Content Development Reference Including resources for publishing content on the Help Server March 2016

2 Help Server guidance Optimizing your investment in content F1 or TOC? Metadata and editing tools for Help Server content How context sensitivity works Issues with topic mapping Metadata properties that display Help from the F1 key Troubleshooting * This document uses the term topic to refer to individual articles in the Help. For example, a topic is the unit of content that s displayed when you press F1. Contents Links to existing resources on MSDN Customizing the Help System Context Sensitive Help Writing Documentation for the Help System Publishing Documentation to the Help System Document Property Metadata Reference Walkthrough: Creating Help Documentation Walkthrough: Publishing Help Documentation Walkthrough: Updating Existing Help Documentation Additional Help Server topics on MDSN Graphics toolkit Using graphics can assist visual learners by showing, rather than telling them complex information. The graphics toolkit includes stencils and examples that you can use to create your own illustrations and process diagrams. The graphics toolkit includes a Visio document and the Dynamics Symbol font. Both are included here. Writing tips Who uses Help: Identifying your audience Guidelines for writing technical documentation Where to find additional help and how to provide feedback Technical support isn t available for this toolkit. Refer to the Visio product documentation for answers to questions about Visio. The most current Microsoft Dynamics AX product documentation for system administrators, IT professionals and knowledge workers is available on TechNet library. Help for developers is available from our Dev center on MSDN. Your feedback is welcome; please send comments and suggestions to adocs@microsoft.com. Templates The Microsoft Word and HTML templates that are included in this toolkit provide a starting point for creating your own content. These templates are installed with Microsoft Dynamics AX and can also be downloaded from MSDN.

3 Optimizing your investment in content What this guide is for Writing documentation takes time and effort. When done well, the return on your investment includes fewer support incidents, users who get more benefit from the software they use each day, and potentially reduced costs from reworking business tasks that weren t done correctly the first time. The Help Server that s built into Microsoft Dynamics AX 2012 includes capability that can help you provide content that s easy for users to find, that provides the help they need, and that s available when they need it. This guide includes information and links to additional resources that can help you gain the full benefit the Help Server can offer. It also points to other tools that can help you produce content that users need. Set goals before you write Your decisions about what content to write will have a significant effect on its longevity. The following points offer a way of thinking about where to focus your investment in developing content. Invest in making the interface clear enough that you don t need more documentation Build usability into the workflow of your application and write UI text that doesn t require additional documentation. Focus your efforts on processes that yield the greatest value Focus on documenting processes that are important to your business, but that aren t completed frequently. Documenting a small number of these kinds of procedures might return more value than writing more procedures that describe routine tasks. Focus your documentation effort on how-to content, rather than field descriptions If your content describes UI elements, nearly every software update will require changing it. How-to content is less likely to change, even when the application is updated. Include essential field descriptions in how-to documentation You can include descriptions of critical fields in procedural steps. Doing so allows you to include information that helps your users without making reference information about forms and fields the focus of your documentation set. Use pictures where they can convey information more effectively than words This guide includes templates and guidance for adding process diagrams to your content. For some processes, a well-designed diagram or illustration can save pages of narrative content. Remember that quantity doesn t equal quality Consider limiting your content to the processes that will have the most impact on your user base. Creating a lot of documentation you don t have time to maintain ultimately returns less value than less content that s of higher quality.

4 Help system components Help Server The IIS web site that s installed with AX that stores content and sends topics to the help viewer when they re requested. Topic A discrete unit of content; which is what we call an article on the Help Server. Help Viewer The component of the Help Server that displays topics in the AX client. Topic ID An identifier that s assigned to each topic. The topic ID is used to display that topic when a user presses the F1 key in the AX client. Disambiguator A list of topics that s displayed in the help viewer, showing topics that are mapped to the same topic ID. Publisher A specific author or organization whose topics are grouped together by storing them in a specific folder and modifying a setting in the Help Server configuration file. Structuring Help Server content The disambiguator, which is shown above, is a list of topics that are mapped to the same form in AX. F1 or TOC? You can set your topics to display when a user presses F1 from a form in AX. You also can update the table of contents (TOC) to include your content in the list of topics that s displayed in the contents pane in the Help. You can always access topics using the search feature of the Help Server. You can enter one or more keywords in a topic s metadata that will improve its discoverability through search. Creating help for business processes The Help Server allows multiple options for documenting business processes, or variations of the same process, that are completed in the same form and displaying that content in the Help. o o o Write a topic for each process and map each topic to the forms that are used to complete the process. When a user presses F1 from that form, a list of the topics will be displayed; the user can select the topic that describes the process they re working on. Write one topic that includes documentation for all of the processes that are completed from that form. You can map that topic to the form and users can search within the topic to find the description of the process they re working on. Write a separate topic for each process, plus an additional topic that you ll map to the form. You can add links to the topic that s mapped to the form you re describing so your users can see a single topic when they press F1, from that topic click a link to the topic that describes the process they re working on. There is no single right way to structure your help topics. The number of topics you re willing to manage and the preferences of your users should guide how you decide to structure your Help topics.

5 Metadata and editing tools for Help Server content Metadata Help Server topics include a number of metadata properties that are used to find and display topics when a user opens the Help. Microsoft.Help.ID An identifier for each topic that must be unique for each topic. This property must be filled in. Microsoft.Help.F1 The AOT name of forms or menu items that associates a topic with a form in AX. This property must be filled in. Publisher The property that identifies a group of topics from one organization or author from another. This property doesn t have to be specified. For more detailed information and guidance for creating content about how to create content for the Help server, see the Help system section in our Dev Center on MSDN. The illustration on the right shows a section of a Help Server template in Notepad that can be used to enter metadata for a topic. (You might need to use the Zoom feature in Reader or Acrobat to view the illustration.) The Microsoft.Help.ID must be unique. Microsoft.Help.F1 associates a topic with a form and this can be used in multiple topics (but it triggers the disambiguator.) Tools to use for writing Help Server topics Help Server content can be written using any HTML editor. Word processing programs, such as Microsoft Word, can be used to create documents and save them in HTML format. However, these programs were intended to create and deliver documents in formats other than HTML. Using a dedicated HTML editor can help you optimize the creation of content you plan to publish on the Help Server.

6 How context sensitivity works on the Help Server Matching objects in the AOT with topics in the Help Server Forms and Menu Items in the AOT Travel & expense workflows TrvParameters Payment methods TrvPaymethod Shared categories Global category Expense categories ProjCategory Delegates TrvApprEmplSub Help Server topics Travel & expense workflows Microsoft Payment methods Microsoft Payment methods Contoso Share categories Microsoft How context sensitivity works When a user presses F1 from a form, list page or menu item, the AX client sends a request to the Help Server that includes the AOT path of the form or menu item. The query searches the Help Server for an item whose Microsoft.Help.F1 property matches the AOT name. If there is a match, the Help viewer returns the topic with the matching Microsoft.Help.F1 property to the client, where it s displayed in the Help viewer. Issues with topic mapping: the disambiguator There are times when multiple topics are returned for a query. If multiple results are returned, a disambiguator topic that lists them all will be returned. Multiple results will be returned more than one topic with different IDs have the same AOT name in the Microsoft.Help.F1 property

7 Troubleshooting Issues that can occur and suggestions for addressing them Topic won t display in the Help Viewer Question: I ve written a topic and entered metadata, but the topic doesn t show up in the Help Viewer. What do I need to do? Answer: Link attributes are case sensitive. If the casing on the attributes is incorrect, the xhtml will be formed incorrectly and the topic won t render in the Help Viewer. Too many topics listed when F1 is pressed Question: I ve written a number of topics and entered metadata so that they ll display when I press F1. But all the topics show up in the same list, instead of displaying individually in a specific form. How can I get them to display in the right form when I press F1? Answer: Each topic must have a unique topic ID, which is set in the Microsoft.Help.ID property. When multiple topics use the same topic ID, they ll all be displayed. Mapping Help topics to forms in AX Question: How can I get the Help Server to display a specific topic when I press F1 in a form, without getting the list of topics (the disambiguator)? Answer: If more than one topic is mapped to the same form, the topics be displayed in the disambiguator when a user opens Help for that form. That happens when more than one topic contains the same entry in the Microsoft.Help.F1 property.

8 Who uses Help: Identifying your audience Key team members IT Professionals Audience types Developers Business process users Cross discipline, responsible for deploying an AX implementation Often includes members of all audience types Responsible for evaluating business process to optimize the AX implementation Responsible for installing and deploying software for their organizations Work with the implementation team to deploy software across the organization Responsible for customizing and extending AX to fit their organization s unique and specific needs Works with IT Pros to import and export data Develop features that fulfill critical business needs Responsible for using AX to complete critical tasks Participate in the implementation team to define business processes Train and support users completing routine tasks Serving the needs of specific audiences Who your audience is influences the tasks and concepts that you describe, terms you use, and amount of detail you include. Knowing your audience also helps you keep the scope of your documentation projects appropriate Key team members are often members of the implementation team. This team understands the industry, business process, and its members configure the system and determine the procedures their end users will complete. Key team members read the product documentation to develop deep understanding of how AX functions and write content to help users complete infrequent tasks. Content needs by audience type IT Professionals need to understand the product architecture and maintenance procedures. Developers need API references and how-to information that helps complete their work as efficiently as possible. Business process users need information that helps them address situations that aren t routine, which helps them complete important but infrequent tasks.

9 Guidelines for writing technical documentation Tone What to write What not to write Technical communication has changed. It s less formal, addresses users directly, and strives to instill reassurance and confidence in users. We use everyday words, short sentences, contractions, and useful graphics. Get to the point quickly. Content that helps users achieve success in their objectives Procedural content that gets users into the software and completing tasks. Descriptions of downstream consequences; help users know what to expect and avoid surprises later. Content that helps users understand decision points. When a user is confronted choices, the need content that helps them understand which choice is right for them. Content for the sake of filling topics Any content because that s the rule. Optimize search The search feature of the Help Server uses the topic ID, the Microsoft.Help.ID property, and search keywords when ranking search terms. Good search keywords are the words your readers use to find information. You don t necessarily need a lot of search keywords. Try to include search keywords in the introduction of your topics. Consider entering two to four search keywords to avoid being too general or too specific, although single words can also be effective. Incorporate synonymous keywords when research suggests it might be helpful, for example, vendor and supplier, or quotation and quote Examples of effective search keywords: Topic title: Setting up and maintaining cost accounting Search keywords: cost; costing; costs; cost accounting; cost control; cost management Topic title: Setting up and maintaining Product information management Search keywords: product, products, product information, product management, product maintenance, product setup, PIM Set reasonable writing guidelines and strive for consistency Setting some constraints help you work because they can provide direction on your work. It s not necessary to be too rigid in their application, but the boundaries that rules provide can make it easier to write, and make your writing easier to read and understand. Titles Microsoft starts conceptual topics with the word about Titles of how-to content start with a verb. Examples include: Setting up and maintaining General ledger Setting up Accounts receivable Avoid generic titles, like General information and Details. Instead, use descriptive titles that tell readers what s in the topic: About posting options, or Implications of posting setup options. Terminology Help users by using clear and common terms the terms they re already using and by using those terms consistently across your product s UI, and your documentation. The glossary in the Help might be a reference, as well as glossaries or references of standard terminology used in your industry.

10 Templates The Help Customization toolkit includes a number of templates. Templates in XML format can be used with the HTML editor to write content for the Help Server. There s also a Word template that can be used to develop content for the Help Server. There s also a template that s intended for use outside the help server. That template might be useful for writing installation instructions, release notes, or other kinds of content that are not published on the Help Server. Working with the Word template for the Help Server The Help Server template contains macros that can help you enter metadata for your topics. You can use the template with Word 2007 or later versions. 1. To open the template, download the template to an accessible location. 2. Start Word, navigate to the template, and open it. 3. Macros are turned off when you open the template. To use them, click the Enable Content button shown in the illustration. 4. Click the Microsoft Dynamics Help menu item, and then click the View Document Properties Advanced selection. The document properties dialog will open where you can enter metadata for the topic in the fields indicated. Replace the existing text in the template with the content that you ll publish on the Help Server. Additional guidance is available on MSDN for developing content using both Word and HTML templates. You can also use Word documents for content that s not displayed on the Help Server. For example, installation instructions are critical to your application. However, they re needed before your product or its Help is installed.

11 Copyright This document is provided as-is. Information and views expressed in this document, including URL and other Internet Web site references, may change without notice. You bear the risk of using it. Some examples depicted herein are provided for illustration only and are fictitious. No real association or connection is intended or should be inferred. This document does not provide you with any legal rights to any intellectual property in any Microsoft product. You may copy and use this document for your internal reference purposes. You may modify this document for your internal, reference purposes Microsoft Corporation. All rights reserved. Microsoft Dynamics is a line of integrated, adaptable business management solutions that enables you and your people to make business decisions with greater confidence. Microsoft Dynamics works like and with familiar Microsoft software, automating and streamlining financial, customer relationship, and supply chain processes in a way that helps you drive business success. U.S. and Canada Toll Free Worldwide