Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: new content-bucket page #1036

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions docs/styleguide/content-buckets.md
Original file line number Diff line number Diff line change
@@ -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.
Loading