Welcome to the Exact Product Blog

On this blog we will cover stories from all around the Exact ecosystem.

Help to improve the SDK documentation!

Written by Michiel Dorjee on . Posted in Exact Globe, Exact Synergy

Exact is offering with the Software Development Kit of Exact Globe and Exact Synergy Enterprise a set of development tools that allows developers to extend our products with additional functionalities and behavior or to connect our products with their own products to exchange information between the products.

Most of the SDK development tools are automatically available when installing Exact Globe or Exact Synergy Enterprise. Having the correct modules in the license will activate the SDK for the developers to develop their solutions on top of our products.

To support our development partners the best, we are constantly looking how to improve the SDK. Examples we currently did, or are working on, are:

  1. Constantly improvements and extension on SDK functionalities,
  2. Extended the SDK training for Exact Synergy Enterprise with a repository section,
  3. Setup development guidelines for solutions on Exact Synergy Enterprise,
  4. Updated the product certification process,
  5. And we recently started to document the most important controls of Exact Synergy Enterprise.

For the development of the solutions we offer our development partners online documentation about the SDK development tools. This documentation is presented on our portal and can only be accessed by our customers, partners and employees. There are two start pages:

We now addressed the SDK documentation as the next step to improve. We already made a start with the documentation of the controls but that’s not the only improvement we would like to make.

I would like to invite you, our development partners, to comment on this blog what you really miss or what you would see improved about the SDK documentation. Based on your feedback I will compile a list of improvements that would make your life easier. In a new blog post I will share this list with you and where we will focus on for the coming period.

I’m looking forward to receive your input.

Tags: , , , ,

Comments (3)

  • Frank van den Hoek

    |

    Hi Gijs and Gerard,

    I made a prioritized list of improvements you could consider below:

    1. Documentation should be linked 1 to 1 with a batch/release. Like Microsoft does per .NET Framework release. So don’t add properties to an existing document with the text behind them saying: ( from batch 395 ). No, just create a document per batch.

    2. I don’t know how documentation is created now but I clearly have the idea that it is done manually. This is normal if we are talking about walk-throughs etc. For object reference documentation this is a different case. I would suggest keeping the documentation closer to the code or in between the code ( XML-doc style ) so documentation can be generated. This improves the accuracy of the documentation because you do not have to keep it in-sync manually.

    3. Expand the documentation. More code examples would be nice but adding some semantics/meaning to properties and methods would be even nicer! For example: The property TransShipment of object SDKSalesOrder now has the following description: Intrastat. References field trsshpm_cd in table intshp, combined with land_iso. This does not tell me for what purpose I should use this property!? It is technical blabla and hardly useful?

    4. Style/markup. The way the documentation is presented is not very clear. For this I refer to Microsoft’s MSDN docs again. This does not mean you have to copy it exactly but I think you could learn from it.

    I hope this is clear. if not, you no where to reach me.

    Good luck!

    Reply

  • Gert

    |

    The main thing is Xml comments, and generate documentation. You can build Help-files that can be integrated within Visual Studio for reference, that’s ideal. But also as regular help, MSDN is really a brilliant example of great helpfiles.

    I wouldn’t really create different pages for each version, but keep it like MSDN: same page but you can select the .Net version and get that specific help.

    Reply

Leave a comment