diff --git a/docs/styleguide/content-buckets.md b/docs/styleguide/content-buckets.md new file mode 100644 index 000000000..5d11179ac --- /dev/null +++ b/docs/styleguide/content-buckets.md @@ -0,0 +1,24 @@ +--- +title: Content Buckets +Description: This style guide explains how and why we use content buckets in documentation. +weight: 30 +--- + +# Content Buckets +To structure our documentation, we adopt a systematic approach from the Diátaxis framework. We ensure our docs are presented in a manner that is easy to understand by organizing and classifying them into content buckets. + +![Diátaxis framework](https://www.asyncapi.com/img/posts/changes-coming-docs/diataxis.webp) + +> Documentation structure based on the [Diátaxis framework](https://diataxis.fr/). + +At AsyncAPI our docs are classified into the following content buckets: + +- **Concepts** - This section is where we define various features and capabilities AsyncAPI offers. All docs pages under this bucket need to be accurate, easy to understand and accompanied by an engineering diagram. We utilize [Mermaid.js](https://mermaid.js.org/) syntax to create diagrams and visualizations. + +- **Tutorials** - Our tutorial section offers practical guidance to individuals who are beginners or new to AsyncAPI. Docs under this content bucket need to be hands-on and provide step-by-step guidance using real-world examples. The docs should be engaging and interactive to help users develop the required knowledge. + +- **Guides** - The guides section teaches individuals about higher-level AsyncAPI features. Content under this bucket helps users gain a deeper understanding and provide different ways to solve a problem. The tone should be concise. + + *You can think of guides as a recipe for cooking a meal.* + +- **Reference** - This section provides detailed technical information about the specification. Under this bucket, you'll find release notes, API and internal documents such as function definitions and parameter descriptions. References need to be precise, straight to the point and accurate.