Example: User documentation

We should prepare a documentation to any application that we create. ObjectGears helps to automaticallygenerate technical documentation - it contains list of all data entities and other objects of the model together with description that we have stated by particular objects.

Other types of documentation usually require well thought-out description that facilitates understanding of the developed application and its functionality by users that should work with it. It is design of the whole system, its relations to the neighbourhood (interfaces), logic of access rights, system support (contact data of administrators and system owners) etc. Particular example is also user documentation that should respond to user questions which may arise at particular screens and also provide an overview of possibilities that the application provides.

We can help user orientation also by description of particular fields, tooltips, placeholders and messages. It is good to use these features that ObjectGears provides. However, a complex description of functionality should be done in form of a comprehensive document (e.g. in MS Word or PDF) or structure of web pages. Both these types of documentation can be stated in ObjectGears model and they will be displayed to users after moving mouse over the question mark icon in the upper right corner of the screen.

We can enter files or url links in the detail of model (our application) on tab User documentation:

We have to create and  upload the file with documentation and for a new version we have to update it and upload again. A more sophisticated approach consists in use of web pages that describe our application from various perspectives and that are connected by links.

Example: Version Controlled Documentation ObjectGears

ObjectGears provides a model for version controlled documentation, in which you can easily create documentation of any system or product. This documentation supports versioning and multiple language versions of the articles. This documentation can then be referred from the given system and ensure that the documentation is displayed to particular users in their respective language and version. We will describe below how to effectively interconnect applications developed in ObjectGears with their documentation created in the model Version Controlled Documentation.

We will create a structure of articles related to our particular application in the Version Controlled Documentation. Each application can have a tree of articles describing its architecture, access rights concept etc. We can create language variants for particular articles and also variants displayed according to the selected application version. Then we add one or more articles to the User documentation in the ObjectGears instance - see above, in form of url links. When referring to a Version Controlled Documentation article we can pass parameters for language and version.

We can pass these two parameters to URL in the following way:

https://doc.objectgears.cz/vcd/#Language#/an/AN0001803/v/#Version#

After user clicks on the documentation link under the question mark icon in the upper right corner of the ObjectGears screen, Version Controlled Documentation is called and it displays the given article in the user language and version. If the given article would not be available in the language selected by the user in ObjectGears, Version Controlled Documentation displays the article in the default language and displays an informatory message.