NAV Documentation Format

Microsoft does not really impose many limitations on what you can do with your help content. Even if your solution is going to achieve certification, you can add any bells and whistles as long as your help content complies with certain requirements. Let’s put aside the route of making a completely different help system for your solution. In this article, we’ll discuss the choices you may face in case you want your solution help to conform to the standard documentation so that you could integrate your custom help content into the standard Help server seamlessly.

Now that standard documentation migrated from chm files to HTML files on the Help Server, Microsoft Office Word or PDF guides are no longer provided apart from some supporting documents. In fact, the documentation is also available on MSDN, with a slightly different layout. This probably means that custom help should also abandon good old User Guides and stick exclusively to Help Server, doesn’t it? Not exactly. It’s all about the purpose you are trying to achieve and how you want to present information to the end user.

Having been using the Help Server for several years now, it is quite obvious that this system cannot be called an all-in-one solution to cater to all your documentation-related needs. Its introduction clearly simplified the internal process of help production. Now you can easily make adjustments even without recompiling the whole project. The help content can be on a server, while numerous Microsoft Dynamics NAV clients may connect to it and all of them will have the latest version. You do not have to think about certain issues that you had to deal in the past, such as index or complex table of contents. On the other hand, the Help Server has its own drawbacks, such as overly simplified search functionality compared to what you had in chm files.

With more than 5 years of experience of using the Help Server, we just realized that we do not want to turn our backs on Word and PDF documents. At least for now. Here’s why.

There are goals that the documentation provided on the Help Server does not really allow us to accomplish. Let’s break down the key differences between Word/PDF documents and online Help on the Help Server.

Help Server (HTML):

• Perfect for context sensitive help. The Help Server provides context-sensitive help for Microsoft Dynamics NAV objects and controls. This of course does not limit this help from providing other information, such as description of concepts or how-to topics to provide assistance in completing tasks.

• Topic-based. Information is provided in small chunks – topics. Thus, in case you want to learn about a specific area, for example, you end up jumping back and forth through hyperlinks. There’s a chance you might skip certain topics or get lost in independent pieces of writing.

• Minimum imagery. Even though an HTML file on a Help Server may include images or screenshots, their amount is reduced to a minimum due to the fact that you have a Microsoft Dynamics NAV client in front of your eyes before opening a help topic or can launch a window directly from certain topics if necessary. This also simplifies the process of documentation maintenance as you do not have to keep up with the slightest changes in UI of your solution.

User Guides (docx/pdf):

• Coherent layout. In contrast to numerous topics on a Help Server, a guide in the docx/pdf format normally has a coherent structure that allows the reader to perceive information in a logical and well-organized way. This is perfect if you want to learn as much information as possible about certain area and want to ensure that each part of it connects or follows in a natural and sensible way.

• Rich in visual aids. Since it is convenient to send a document to somebody without the need for them to install the Help Server or even Microsoft Dynamics NAV, such a document normally has an abundance of images, because the target reader may not have access to Microsoft Dynamics NAV. The downside of this is that update of such documentation may become a troublesome matter.

• Independent: Such documentation does not require Microsoft Dynamics NAV or Help Server. This may be useful when you need to provide quick assistance and want to avoid any deployment-related hassles.

As you can see, neither route is ideal. Our approach at present is to stick to both these formats that complement each other. Thanks to Microsoft’s support for Word documents on the Microsoft Dynamics NAV Help Server, you can make your documents available for download from the Help Server, in addition or instead of online Help content. As for pdf files, they are partially supported: you can download them from the server, but you cannot read them directly through a web browser out-of-the-box. Although, with slight modification of the msdnTheme.css file, reading a pdf on the Help Server may become another option for the reader. We believe the more options for the user the better. Let them choose what’s best for them.

Another point to consider when you decide which format to choose for your documentation is how you are going to support it in the long run. If your solution is a long-term project which is going to grow, while your documentation team is unlikely to change, later you might face the issue of documentation update: how to cope with constant modifications in a myriad of topic files in a behemoth-sized project. While Microsoft Office Word provides a remarkable Track Changes feature, which may save you from becoming entangled in those countless updates throughout the project, your HTML editor will not necessarily have such functionality. This is not an issue for a small project, but may turn into headache for a colossal ever-changing solution.

What about the future?

The current iteration of the Help Server is definitely not final. The help team at Microsoft is aware that managing help on Help Server may be cumbersome and are looking for ways to improve it. The Help Toolkit has not been updated for quite a while. So, you shouldn’t be surprised to find out that the latest version of for Microsoft Dynamics NAV 2013 R2. Note that it still can be used to create help content for later version of Microsoft Dynamics NAV.

In Microsoft Dynamics NAV 2017, tooltips were introduced, which enable you to create a brief unblocking help for field and action controls by simply filling in a property of a control. Tooltips are part of the new 3 layers approach to user assistance:

• Get Started

The user interface is (as close as possible to) self-explanatory.

This is why you'll notice changes in many page objects and the introduction of new setup guides.

• Get Unblocked

Embedded user assistance ("tooltips") to answer most questions.

This is why many page objects now contain tooltip text.

• Learn More

Conceptual topics on Help Server describe scenarios, workflows, and capabilities.

These three layers are work in process, but this is a foundation for the future. The NAV User Assistance team has moved to a new toolset, based on Open Source Software and GitHub-flavored MarkDown. HTML files are generated using DocFx, which results in far cleaner HTML. However, more information about this new toolset is still to be provided later on. We look forward to more news regarding these changes. Hopefully, they will make our life simpler and more exciting going forward.

So, which documentation format to choose is the choice that you should make taking into account your goals, business needs, and preferably the end user’s needs. Choose the best strategy that will benefit all sides in the long term and be ready for changes that may come upon us in the near future.