Dynamics NAV and Help: A new world
With Dynamics NAV 2017, we bring user assistance and developer docs to new platforms that makes updates and collaboration far easier than ever before. In this blog post, we’ll explain what this move means to you, and we’ll invite you to join us in our travel towards a new world.
Developer and IT-pro documentation
With Dynamics NAV 2017, we have moved the developer and IT-pro content to a new location in MSDN:
This is the only location for the content, because we removed cside.chm from the development environment. As a result, it will be easy for you to get the latest version of the content because it’s online only.
The content is written in GitHub-flavored MarkDown in a GitHub repo based on Open Source Software. We are still making the final changes, but very soon this blog post will be updated with a link to our coming public GitHub repo. This means that you will be able to contribute to our content, such as suggesting new code examples, or making clarifications in our content.
Dynamics NAV 2017 is one of the first Microsoft products to go live on this platform, so this is new to all of us. But you can see how it will work (almost) on the equally new docs.microsoft.com site.
The downside of being one of the first products on a new platform is that the platform is still evolving.
As a result, we are not able to publish the Help for our Windows PowerShell cmdlets online yet. But you still have access to Help for the cmdlets and their parameters using the Get-Help command in the Administration shell or the Development Shell. Update: We were not able to publish the Help for our Windows PowerShell cmdlets at launch, but now they are available online: https://msdn.microsoft.com/en-us/dynamics-nav/windows-powershell-cmdlets-for-microsoft-dynamics-nav.
Redefining user assistance
In Dynamics NAV 2017, we introduce a new format for Help with an emphasis on 3 layers of 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.
This is why we removed the existing Help Server content from the product media to create a reasonably clean slate.
All three layers are work in process, but Dynamics NAV 2017 provides us with a platform that we will build on that we will build on in the coming releases. But let’s dig deeper into the here-and-now.
Since Dynamics NAV 2013 R2, we’ve received feedback about Help Server and the pros and cons of this lightweight web site and the many thousands of topics that Microsoft shipped on the DVD in each release. For each language, Help Server contained more than 20,000 topics, the vast majority of which did not contain any changes from version to version.
It has been challenging for us to maintain this large library, and we’ve been told by some of you that you really didn’t enjoy the rather cumbersome work of modifying the HTML files – especially since we didn’t provide you with any tools but did provide you with very complex HTML that our internal tooling generated.
We have now moved to a new toolset for creating Learn More content that results in far prettier HTML files. You can see this new format in the new, smaller CAB files on the DVD for the RTM version of Dynamics NAV 2017, such as help-en-US.cab. This new toolset is based on Open Source Software and GitHub-flavored MarkDown. The HTML files are generated using DocFx, which results in far cleaner HTML. More about the new toolset in a later blog post.
But where are the docs?
The DVD contains only the new content that we have written using our new toolset. We had planned to provide you with two sets of Help: the new, smaller CAB files with the new content, plus the legacy Help. For technical reasons, this was not possible to do (long story that ends well eventually). So we chose to give you the new Help content on the DVD, and then give you the big packages of rebranded legacy Help later. Some of you disagree with our choice, and we recognize that. But while you wait for us to make the rebranded legacy docs available to you, think about this:
- If you’re upgrading existing customers (or if you are an existing customer), then you already have the content from the Dynamics NAV 2016 DVD. And your current Help Server contains that plus any customizations, even.
- Depending on your implementation, the Microsoft content for large areas of the application hasn’t really changed from one version of Dynamics NAV to the next, as some of you have pointed out in the past.
In other words, most of you can just upgrade to Dynamics NAV 2017 and start using it in your daily work as before. Customizations and add-ons on Help Server are the same as before, unless you choose to convert your user assistance to go the same way as we have: Tooltips and a reduced number of conceptual topics on Help Server.
Update: You can download packages of HTML files for Help Server that contains the Microsoft Dynamics NAV 2017 Classic Help. The download consists of 45 CAB files with the content from the Dynamics NAV 2016 DVD rebranded to Dynamics NAV 2017. There are CAB files with the W1 application Help translated into each of the supported languages plus the local functionality for the country/region where that language is spoken. There are also CAB files with local functionality in English. We have chosen to make this a single download so each of you can choose exactly the files that you need. For more information, see Microsoft Dynamics NAV 2017 Classic Help Download.
A new world of collaboration
All of this is work in process, and we will publish updates to MSDN frequently, and we’ll publish our GitHub repos so that we can collaborate with you on the content. We in the NAV UA team truly look forward to this new world, and we hope that many of you will join us.
In this new world, we use Open Source Software, which means that you can choose to use the same tools as we do: Visual Studio Code, Atom, and DocFx. And you’ll be able to fork our coming public application repo and make your customizations in your copy of our source files. You’ll be notified if we publish updates, and GitHub will help you merge our changes into your content.
All of this work-in-process is confusing to some and slows down others – we recognize that, and we are working hard on making things simpler for you going forward. More about this in a few weeks, we expect.
The NAV User Assistance team
Blog post updated on December 2nd 2016 with link to Windows PowerShell cmdlet documentation online. Also updated on December 5th with link to download of the rebranded legacy Help.