documentation review

Author: ppoetsma

.vscode/settings.json

@@ -23,4 +23,7 @@
     "markdown.preview.fontFamily": "\"IA Writer Duo S\", monospace",
     "markdown.preview.lineHeight": 1.8,
     "markdown.extension.toc.levels": "2..3",
+    "markdownlint.config": {
+        "MD033": false
+    },
 }

DOCS/example-app.md

@@ -8,23 +8,27 @@
 
 ## Introduction
 
-The example app is used to test the integration Docmosis module. Therefor it can be used by you to see how you can implement the module in your own app.
+The example app is used to test the DocmosisCloud module. Therefor it can be used by you to see how you can implement the module in your own app.
 
 ## Where to find the app
 
-Download the [latest version as zip file](https://github.com/Docmosis/mendix-tools/archive/main.zip) or use git to clone it from the [GitHub repository](https://github.com/Docmosis/mendix-tools).
+Download the [latest version as zip file](https://github.com/Docmosis/mendix-integration/archive/main.zip) or use git to clone it from the [GitHub repository](https://github.com/Docmosis/mendix-integration).
 
-If you want to run the app then open it in Mendix Studio Pro and in the profile update the two DocmosisCloud module constants with your access key and end point.
+If you want to run the app then open it in Mendix Studio Pro and in the profile update the two DocmosisCloud module constants with your access key and end point. Or start the app and enter the access key on the home page in the appropriate field.
+
+> ATTENTION: This example app exposes the API access key visually. So when you want to hide it then remove the field(s) from the app's home page.
 
 ## What is in the app
 
 These modules are in the app:
 
 - **DocmosisCloud:** That is [the module](module.md) where this is all about.
 - **DocmosisSamples:** The business entities to manage customers, products and invoices and trigger the creation of PDFs.
-- **DocmosisCloudImplementation:** This module implements the module in this specific app with its specific needs. Here decision are made how to create PDFs, how to handle errors, etc. This is specific to the app, operational needs, etc,
+- **DocmosisCloudImplementation:** This module implements the module in this specific app with its specific needs. Here decision are made how to create PDFs, how to handle errors, etc. This is specific to the app, operational needs, etc.
 - **DocmosisCloudUnitTesting:** Implementation of unit tests for the [DocmosisCloud module](module.md), directly related to development of it.
 
-This is what the app looks like in terms of layers. DocmosisCloudUnitTesting is out of scope.
+> In case of errors or other unforeseen events the module does not log errors or show messages to the user. It is up to your app to decide what to do. Hint: Use module **DocmosisCloudImplementation** to get inspiration how you could implement this in your app so it matches your operational need.
+
+This is what the app looks like in terms of layers. Module **DocmosisCloudUnitTesting** is not in scope.
 
 ![Module](assets/Modules.png)

DOCS/module.md

@@ -25,6 +25,8 @@ The module is a wrapper around the Docmosis web services. This are the actions i
 2. **Execute the request:** The data is transformed to a proper web service request and send to Docmosis. The response is interpreted and in case of an error details of the error are stored in the response.
 3. **Interpret the response:** In case of a successful execution the response contains the requested data. See the [Docmosis Cloud DWS3 Web Services Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-web-services-guide) for details and examples. In case of an error you will find error details, see [paragraph Generic response object attributes](#generic-response-object-attributes).
 
+> In case of errors or other unforeseen events the module does not log errors or show messages to the user. It is up to your app to decide what to do.
+
 ## Create a template
 
 Before you can actually render documents you have to create a template. See the [Docmosis resources website](https://resources.docmosis.com) and in particular the [DWS3 Template Guide](https://resources.docmosis.com/content/documentation/cloud-dws3-template-guide) how to create a template.
@@ -33,7 +35,7 @@ Use Docmosis Cloud Console to upload the template.
 
 ## Generate the data structure in your app
 
-In your app you have to collect all required data and structure that in such a way that it is compatible with the template you created. The module offers a function that supports you in generating a non-persistent data structure.
+In your app you have to collect all required data and structure it in such a way that it is compatible with the template you created. The module offers a function that supports you in generating a non-persistent data structure.
 
 In case you want to create the structure manually then you can skip the remainder of this paragraph. Otherwise continue reading and the [example app](example-app.md) shows how you can use it yourself.
 
@@ -127,10 +129,10 @@ Every response has these attributes:
 
 - `Result`: an enumeration specifying the overall result
   - `Success`: the happy flow
-  - `Error`: the web service request succeeded, but there was an issue with the template, data or otherwise
-  - `Exception`: the web service request failed
+  - `Error`: the web service request succeeded (HTTP status code 2xx), but there was an issue with the template, data or otherwise
+  - `Exception`: the web service request failed and generated an exception
 - `ShortMessage` and `LongMessage`
-  - these attributes are set by Docmosis and contain feedback, so likely then the request was not successful
+  - these attributes are set by Docmosis and contain feedback
 - `RequestID`: copied from the request object, see [Generic request object attributes](#generic-request-object-attributes)
-- `Http`: Http response details like the request URL used and technical details returned by the Docmosis Cloud; this is helpful in troubleshooting errors
-- `Exception`: in case `Result=Exception` here you will find Mendix exception details, copied from `$latestError` so similar to the `System.Error` entity
+- `Http`: Http response details like the request URL used and technical details returned by Docmosis
+- `Exception`: in case `Result=Exception` here you will find Mendix exception details, copied from the `$latestError` object

README.md

@@ -14,7 +14,7 @@ Output formats can be PDF, Doc, DocX, ODT, HTML and RTF; one at time or multiple
 
 This Mendix module simplifies generating documents from your app using Docmosis. It is a wrapper around the Docmosis web services. All you need is a Docmosis access key and a good understanding of your reporting needs and the data in your app. The module handles all web service complexity so you don't have to be an expert on that and you can focus on generating documents.
 
-In the [GitHub repository](https://github.com/Docmosis/mendix-tools) you will find a project with some showcases and feel free to copy it to your own project or use it as inspiration. The author of the module uses it to test the module.
+In the [GitHub repository](https://github.com/Docmosis/mendix-integration) you will find a project with some showcases and feel free to copy it to your own project or use it as inspiration. The author of the module uses it to test the module.
 
 ## Where to go next?
 
@@ -26,4 +26,4 @@ In the [GitHub repository](https://github.com/Docmosis/mendix-tools) you will fi
 
 The module is published with an [Apache v2 open source license](https://www.apache.org/licenses/LICENSE-2.0). Support is not covered by your Docmosis contract but provided per best effort.
 
-Any questions, issues and requests for additional functionality can be posted to the [GitHub issue tracker](https://github.com/Docmosis/mendix-tools/issues) or can be send by [mail to Docmosis Support](mailto:support@docmosis.com).
+Any questions, issues and requests for additional functionality can be posted to the [GitHub issue tracker](https://github.com/Docmosis/mendix-integration/issues) or can be send by [mail to Docmosis Support](mailto:support@docmosis.com).