1. STAEDEAN documentation guidelines and processes
  2. Documentation processes
  3. Concepts

Why publish documentation in the way we do?
Concept

 

Introduction

The (pragmatic) choice is made to continue using RapidValue as documentation creation and publishing tool.
In this article, you can find a short description of the considerations that led to this decision.
 

History

  1. In the early years of AX7 (later D365 F&SCM), Microsoft didn't have a clear approach on the help documentation. They changed plans, techniques, methods, etc. several times over the course of about 3 years. All this time not giving their partners something they could build their documentation approach on.
  2. After having wait for quite some time, a work group was initiated by Bjorn to come with our own documentation approach. Conclusion was that RapidValue would be the best approach forward. Provided that a web publishing function was added to RapidValue. Which the RapidValue team has added based on this conclusion.
  3. In the meantime, it appeared that also Rine had initiated a workgroup/plan about product documentation, fully focusing on Confluence as the tool to go forward. We joined forces. We agreed on most of the requirements, but didn't agree on the tools to be used. Some of the disadvantages of Confluence compared to RapidValue were: License/subscription to be paid while RV is free, no task guide/recording possible from Confluence, and all available content in RV must be converted to Confluence.
  4. A new workgroup was initiated, with several colleagues from several parts of the organization. Again, there was agreement on the basic requirements, but no agreement could be reached on the tooling to be used.
  5. In the meantime, Microsoft still didn't have clear guidance on how to do/publish custom documentation for D365 F&SCM.
  6. In the meantime, documentation creation continued, using RapidValue. However, documentation still wasn't published. To-be-published documentation was piled up for about 3 years. Sitting there unused. In the Q2/Q3 2018 timeframe, when starting with the EDI documentation, Henk Rietveld (Development Manager) made the final decision that we couldn't longer justify waiting for Microsoft nor for internal agreement on tooling. And this while we had an in-house tool available that could do the job. So, in Q3 2018, the available documentation was published to our docs.to-increase.com.
  7. In November 2018, Microsoft published their custom documentation approach/guidelines.

Microsoft documentation-publishing support

Microsoft provides an instruction and some tooling to create custom help and integrate it with the standard D365 F&SCM help documentation. Refer to the Microsoft documentation on deploying custom help.
Advantages of creating and publishing custom help in the Microsoft way:
  • The help for the STAEDEAN products is integrated with the standard D365 F&SCM help.
  • There's an option to create context sensitive help, which links to the help website.
Creating custom help in the Microsoft way, has some disadvantages as well:
  • Microsoft doesn't provide us with their (full) documentation tooling.
  • It requires an investment in tooling. Examples are (depending on the chosen path): Build a MarkDown and/or JSON output option to RapidValue, build an integration of RapidValue with GitHub, etc..
  • Or a new documentation tool must be chosen that already supports MarkDown and/or JSON, which also should be integrated with GitHub.
  • You must clone the standard D365 F&SCM documentation and publish it together with your documentation. With the frequent D365 F&SCM documentation updates, we also must frequently update this by creating a new clone and adding our documentation to it almost every month. This way we're also responsible for the standard D365 FO documentation.
  • With all the D365 F&SCM solutions that we as STAEDEAN have, it becomes quite troublesome and time-consuming to link our documentation to the new clone again-and-again for each update of our own or the standard D356 F&SCM documentation.
  • It gives less possibilities to promote our own STAEDEAN brand solutions and the related product documentation.

RapidValue as documentation creation and publishing tool

Advantages of creating and publishing help with RapidValue:
  • It's an in-house built tool that's proven as a very useful documentation tool. RapidValue has served that goal for years already.
  • RapidValue has out-of-the-box publish-to-web functionality.
  • All our D365 F&SCM documentation, so far, is already created using RapidValue. (Changing tools, means that all content must be converted or redone. To convert the existing content, a conversion tool is required, probably to be build by our development team.)
  • No customer or partner so far has asked for context-sensitive help.
  • No investments required in time and money to build tooling and integrations.
  • So far, we've only received positive feedback on our website. (Example: an employee of one of our partners learned himself RapidValue from the published RapidValue documentation.)

  • For at least most Data Management solutions, context-sensitive help is built in. For this, the meta data is used that is included automatically in the task recordings. When on a page of a STAEDEAN solution for D365 F&SCM, a help button is shown in the Action Pane of the page. Clicking this button guides you to all task/activity topics that are related to the page.

Disadvantage of using RapidValue: The published help is not integrated with the standard D365 F&SCM help.

Markdown

Some considerations on the use of Markdown in our documentation:
  • MSFT uses Markdown as a means to create their D365 F&SCM documentation. Based on the Markdown source, the documentation is published to HTML.
  • In To-Increase, using RapidValue, we directly write in HTML. So, no extra conversion is required on publishing.
  • So far, we've chosen to publish our documentation separately from the standard D365 F&SCM documentation. Using Markdown only comes into the picture if we choose to fully embed our documentation into the standard D365 FO documentation.
  • If we would use Markdown as a documentation 'language', the buy-in and help from non-technical writers to create content probably will decrease drastically.
  • Using Markdown as content 'language' in RapidValue, will decrease the buy-in from partners and customers on the use of RapidValue.
  • Moving to Markdown as source 'language' for our documentation will be quite an investment. Think of, for example, investigations, converting the current content, obtaining and setting up new tools, and education on/learning of new tools.

Conclusion

Considering and comparing the (dis)advantages of the Microsoft way and the RapidValue way to create and publish documentation, we concluded that the best way to go forward is to continue using RapidValue as the documentation creation and publishing tool for our D365 F&SCM products. Choosing another documentation creation and publishing path, requires serious investments in both time and money.

Related to Notes

Set up and maintain docs.staedean.com website

 		 

Publish documentation to docs.staedean.com