Explanation documentation
← All workContext / Problem
Pricing and discounts is one of the largest surfaces in commercetools, with its concepts reaching into other domains like products, carts, and orders. Its behaviour was split across 10 API reference pages. Each documented a mechanism in isolation, and none explained how they came together.
Approach
New to the domain, I used the project to work out how the concepts fit together with other areas of the product.
To write the documentation, I:
- Worked with support and training to find the questions customers were asking.
- Structured the information as a concept model instead of a topic list, explaining what each concept is for and when to use it.
- Explained how the mechanisms behave when they interact, which no existing page covered.
Outcome
- Reduced the pages a reader consults to understand the pricing and discounts behaviour from 10 to 1.
- Improved readability of API reference pages by removing conceptual and behavioural information.
Solution architects, developers, support engineers, and trainers treat this page as the source of truth for how the commercetools platform behaves in this domain.