Bad documentation structure

[bauer-at-work]

Issue description

Sorry, I can't help myself but open such a generic issue.

The documentation is badly structured and inconsistent in form.
Just an example: Inside chapter "Operating and Monitoring Cloud Integration > Monitoring",
there is a section "Manage Security > Managing Access Policies".

How does managing something fit in a category that is supposed to talk about monitoring?
Over the past decades, SAP has written countless documentations for all the different products.
When I started working with SAP products, the first thing that stood out to me was the quality of documentation.
But now, in the BTP realm, I as a customer get the feeling that not enough effort was spent on documentation.

The documentation needs to follow a clear structure for the reader to be able to follow/digest/understand effectively.
Every technical writer will tell you that.

• Do you use gerund form or not (manage vs. managing)?
• content specific to Neo and Cloud Foundry respectively just being spersed inbetween other sections
• Different areas of interest (security, monitoring, general operations, ...) are mixed

Honestly, I don't even know where to start...
I can only assume that the documentation grew organically, which in this case is just an euphism for a lack of governance / top-down planning in regards to documentation structure.

Please, please, tell me that you can bring this up in the team, slice the elephant and work on revamping the documentation from the ground up.

Thank you for your support!

Feedback Type (Optional)

content structure

Page Title on SAP Help Portal (prefilled)

Defining Access Policies

Page URL on SAP Help Portal (prefilled)

https://help.sap.com/docs/cloud-integration/sap-cloud-integration/define-artifacts-to-be-protected?locale=en-US&q=PI_Administrator

[pe-gu]

Dear @bauer-at-work,

Thank you for taking the time to provide such detailed feedback. I appreciate your engagement and will address several of the points you brought up.

In response to your concern about the structure of the documentation and the inclusion of managing tasks under the "Monitor" section, I want to explain that our documentation is structured in alignment with the user interface. The "Monitor" section covers a variety of tasks, including message monitoring, monitoring of deployed artifacts, and managing security artifacts and storages, among other activities. Our decision to maintain this alignment with the UI was made to ensure consistency and usability for our users.

Regarding your valid point about the inconsistency in the use of gerund and imperative forms (e.g., "managing" vs. "manage"), we acknowledge this issue and will work on harmonizing the language used in our documentation.

With regards to the specific references to the Neo and Cloud Foundry environments, I want to clarify that we made a deliberate decision not to create separate documentation sets for each environment, as the overlap of features and topics would have been significant. Therefore, we indicate environment-specific features and parameters as necessary, but only in the SAP Cloud Integration (standalone) documentation. In the SAP Integration Suite documentation, these environment-specific details are not present.
Example:
The mentioned topic as part of the SAP Cloud Integration (standalone) documentation: https://help.sap.com/docs/cloud-integration/sap-cloud-integration/define-artifacts-to-be-protected
The mentioned topic as part of SAP Integration Suite documentation: https://help.sap.com/docs/integration-suite/sap-integration-suite/define-artifacts-to-be-protected

I hope this addresses some of your concerns, and I want to assure you that we take your feedback seriously and will continue working to improve our documentation.

Thank you for your support and for bringing these important points to our attention.

[pe-gu]

Thank you for your contribution!