Skip to content

Commit 043c399

Browse files
thulieblackAahil13
authored andcommitted
docs: new content-bucket page (asyncapi#1036)
Co-authored-by: V Thulisile Sibanda <[email protected]>
1 parent 90942b5 commit 043c399

File tree

1 file changed

+24
-0
lines changed

1 file changed

+24
-0
lines changed

docs/styleguide/content-buckets.md

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
---
2+
title: Content Buckets
3+
Description: This style guide explains how and why we use content buckets in documentation.
4+
weight: 30
5+
---
6+
7+
# Content Buckets
8+
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.
9+
10+
![Diátaxis framework](https://www.asyncapi.com/img/posts/changes-coming-docs/diataxis.webp)
11+
12+
> Documentation structure based on the [Diátaxis framework](https://diataxis.fr/).
13+
14+
At AsyncAPI our docs are classified into the following content buckets:
15+
16+
- **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.
17+
18+
- **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.
19+
20+
- **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.
21+
22+
*You can think of guides as a recipe for cooking a meal.*
23+
24+
- **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.

0 commit comments

Comments
 (0)