chore(docs): restructure and rewrite content in documentation and quality standards chapters

api-guidelines/global/core-principles/documentation.md

@@ -1,57 +1,35 @@
 # Documentation
 
-Our [quality standards](./quality-standards.md) define all the values that are important to us.
-What's more, we aim to take care of clearly structured documentation, provide our audience with code examples, and make sure they have a great time using our API.
-Here's what that means:
+We strive to make API implementation a breeze with meaningful, easy-to-understand documentation.
+This includes, but is not limited to:
 
-:::: accordions
-::: accordion Clear structure
-**Usability**
+- [Accessibility and usability](#accessibility-and-usability)
+- [Code examples](#code-examples)
+- [Context and walkthroughs](#context-and-walkthroughs)
+- [Up-to-dateness](#up-to-dateness)
 
-- A user-friendly navigation makes it easy to discover the API and find all relevant information.
-- The sidebar is cleary structured and easy to navigate.
-- API endpoints and examples are shown in context.
+## Accessibility and usability
 
-**Getting started**
+- We provide access to all API endpoints in a central location, some sort of documentation portal at the best, to ensure that users can easily use the API.
+- The documentation is browsable across all available endpoints.
+- A well-structured navigation ensures that the documentation can be navigated.
+- We give users the chance to get in touch with us.
+- All information is easily discoverable, easy to digest, and prepared in a way that users can effectively work with it.
+- We are consistent with our tone of voice, terminology, attribute names, API endpoint design, requests and responses, and counting.
+- The layout supports usability accordingly, e.g. with syntax highlighting or multi-column layout.
 
-- Basic information is available at one central place, such as info about HTTP methods, API operations, request/response headers, versioning, pagination, or errors.
-- A short and simple guide provides an overview of the most likely tasks to perform with the API.
-- Users can get in touch with us via a contact form.
+## Code examples
 
-**Tutorials**  
-With step-by-step walkthroughs we'll cover specific functionality that can be implemented with the API.
+- Every endpoint documentation comes with examples and also provides schemas listing the available attributes with explanatory text.
+- Request and response examples that belong to every endpoint documentation have meaningful default values that in the best case follow a specific story.
+- API reference documentation is created and published automatically, see [MUST provide API specification using OpenAPI](../../rest/contract/openapi/rules/must-provide-api-specification-using-openapi-for-rest-apis.md).
 
-**Familiarize users with the API**  
-We'll cater for experienced users that already have an idea of the endpoints to be used, and at the same time provide the respective structure and information for inexperienced users who need a thorough introduction and/or example use cases.
+## Context
 
-**Discoverable and easy to digest**
+- We give context for API usage such as information about HTTP methods, API operations, request and response headers, versioning, pagination, or errors.
+- We cater for experienced users that already have an idea of the endpoints to be used and at the same time provide the respective structure and information for inexperienced users who need a thorough introduction, example use cases, or both.
 
-- All information is easily discoverable, easy to digest, and prepared in a way that the user can effectively work with it.
-- We'll be consistent with our tone of voice, terminology, attribute names, API endpoint design, requests and responses, and counting.
-- The layout supports accordingly, e.g. with syntax highlighting or multi-column layout.
-  :::
+## Up-to-dateness
 
-::: accordion Code examples
-**Default values**  
-Request and response examples that belong to every endpoint documentation have meaningful default values that follow a specific story.
-
-**Code examples and schemas**  
-Every endpoint documentation comes with examples and also provides schemas listing the available attributes with explanatory text.
-
-**Automated API reference documentation**  
-API reference documentation is created and published automatically, see [MUST provide API specification using OpenAPI](../../rest/contract/openapi/rules/must-provide-api-specification-using-openapi-for-rest-apis.md).
-:::
-
-::: accordion Consistency and accessibility
-
-- Documentation is provided in American English (EN-US), as US spelling has become the standard in APIs. Also endpoints, properties, and default values are provided in American English.
-- Users can search the documentation.
-- The sidebar is available at all times so that the documentation can be easily browsed. All the endpoints can be accessed via the sidebar.
-- Code examples and explanatory text are visually separated.
-  :::
-
-::: accordion Efficient and refined
-The API is well-documented and up-to-date.  
-Users can flawlessly integrate and are informed about recent changes via a revision history.
-:::
-::::
+- The API is well-documented and up-to-date.  
+- Users can integrate easily and keep up-to-date with the latest API changes.

api-guidelines/global/core-principles/quality-standards.md

@@ -1,41 +1,49 @@
 # Quality standards
 
-As already mentioned, [the scope of the OTTO API](./api-scope.md) ranges between a public and a private API.
+[The scope of the OTTO API](./api-scope.md) ranges between a public and a private API.
 Nevertheless, when it comes to quality, we strive for the standards of a public API.
-If our API needs to be public by tomorrow, external users should then be able to consume our API immediately.
+If the API needs to be public by tomorrow, external users should then be able to consume the API immediately.
 What's more, a consistent understanding of quality standards facilitates the development of further endpoints and the evolution of the OTTO API as a product without unnecessary consultation between all parties involved.
 
 Our understanding of quality covers the following aspects:
 
-::::: accordions
-:::: accordion Robustness
-All implementations of our API follow the [Robustness Principle](https://en.wikipedia.org/wiki/Robustness_principle), as it is essential for the evolution of APIs.
+- [Robustness](#robustness)
+- [Consistency](#consistency)
+- [Reliability](#reliability)
+- [Security](#security)
+- [Performance](#performance)
+- [Documentation and support](#documentation-and-support)
+- [Communitcation](#communication)
+- [Developer experience](#developer-experience)
+
+## Robustness
+
+All implementations of the API follow the [Robustness Principle](https://en.wikipedia.org/wiki/Robustness_principle), as it is essential for the evolution of APIs.
 Future changes to interfaces cannot be anticipated in advance, so aspects such as backward compatibility, loose coupling, and the elimination of the need to synchronize different services are of crucial importance.
 This is especially applicable for microservice environments where dependencies between services should be kept to a minimum.
 
-::: info Info
-Be conservative in what you do, be liberal in what you accept from others.
-:::
-::::
+We follow the principle: *Be conservative in what you do, be liberal in what you accept from others.*
 
-:::: accordion Consistency
-Our API is essentially developed by independent, autonomous functional teams.
+## Consistency
+
+The API is essentially developed by independent, autonomous functional teams.
 However, we strive for a uniform presentation to the outside world.
 The API should give the impression that it was developed by a single team.
 This consistency covers several facets such as documentation, naming conventions, code examples, common data structures, pagination, governance, authentication, and error codes.
-::::
 
-:::: accordion Reliability
-If our API infrastructure is not reliable, consumers will not build trust, and engagement will not increase.
+## Reliability
+
+If the API infrastructure is not reliable, consumers will not build trust, and engagement will not increase.
 API reliability extends beyond uptime.
 We do not limit our evaluation to availability, but also include aspects such as fluctuations in response times or behavior with an increasing number of concurrent API clients.
 
 We avoid unannounced changes and prevent outages to the best of our knowledge.
-When having to choose between consistency (always return even in case of an error) and availability (in doubt return stale content), we prefer availability. Even to the detriment of consistency.
+When having to choose between consistency (always return even in case of an error) and availability (in doubt return stale content), we prefer availability. 
+Even to the detriment of consistency.
 Our endpoints must always return a response, whether the requested operation succeeds or fails.
-::::
 
-:::: accordion Security
+## Security
+
 Security is not a marginal topic, but an integral part of all software projects, and thus also of APIs.
 
 Not all vulnerabilities will be preventable.
@@ -46,30 +54,27 @@ We are conservative in exposing our data and the [Principle of least privilege](
 In addition, we strive to include only the least amount of data necessary to respond to any API call and secure our applications against the [OWASP Top 10 Threats](https://owasp.org/www-project-top-ten/).
 
 We also restrict the rate limit to specific resources to prevent misuse.
-::::
 
-:::: accordion Performance
+## Performance
+
 We identify and analyze key metrics for different groups of interest.
 The bandwidth of possible metrics ranges from purely technical information such as uptime, latencies, and error rates to business insights such as SDK, version adoption, as well as Time to First Hello World (TTFHW), or API usage growth.
-::::
 
-:::: accordion Documentation & Support
-We help both vendors during development and users of our API with the integration by offering suitable ways of exchange and support.
-As the primary resource for explaining our API and its capabilities, documentation must be as accessible to the audience as possible.
-We provide all consumers of our API with comprehensive, professional, up-to-date, and complete information.
-::::
+## Documentation and support
 
-:::: accordion Communication
+We help both the providers during development and the users of the API with the integration by offering suitable ways of exchange and support.
+As the primary resource for explaining the API and its capabilities, documentation must be as accessible to the audience as possible.
+We provide all consumers of the API with comprehensive, professional, up-to-date, and complete information.
 
-We always keep both developers and consumers of our API informed through appropriate channels.
+## Communication
+
+We always keep both providers and consumers of the API informed through appropriate channels.
 Changes and [deprecations](../../rest/compatibility/README.md#deprecation-of-http-apis) are communicated regularly and actively.
 Therefore, we establish different synchronous and asynchronous communication channels to support developers and consumers.
-::::
 
-:::: accordion Developer Experience
-API consumers should have fun using our API.
+## Developer experience
+
+API consumers should have fun using the API.
 Our goal is to provide seamless experience to developers when writing software, and to increase their efficiency.
-API consumers should be comfortable using our API in their programming language of choice, finding the functionality they need, as well as using the output.
-We give developers the right tools to help them succeed and aim to provide an as short as possible TTFHW.
-::::
-:::::
+API consumers should be comfortable using the API in their programming language of choice, finding the functionality they need, as well as using the output.
+We give developers the right tools to help them succeed and aim to provide an as short as possible Time to First Hello World (TTFHW).