asyncapi / asyncapi/website

Title: Missing prerequisites for running Kafka in Kafka tutorial sequence

Open
#5,191 3 comments 0 reactions 0 assignees View on GitHub
stale
Dominant language
TypeScript
Stars
716
Forks
1.2k
Avg merge
1d 12h
Merged PRs (30d)
35

Description

Description:
The Kafka tutorial sequence assumes that a Kafka broker and local environment are already configured, but the documentation does not provide setup instructions or clearly list prerequisites.
As a result, new users cannot fully run the examples even when following the tutorial step-by-step.

Locations:
- "Create AsyncAPI document for applications consuming from Kafka"
- [https://www.asyncapi.com/docs/tutorials/kafka]
- "Describe Kafka message payload using Avro Schema"
- "Managing schemas using Schema Registry"
- "Kafka bindings"

Observed behavior:
The tutorials reference Kafka brokers and configurations but do not explain:
- how to run Kafka locally
- required tools or environment setup
- how Kafka connects to the Schema Registry container

Expected behavior:
Each tutorial in the Kafka sequence should include or link to a prerequisites section explaining:
- minimal Kafka local setup (e.g., Docker)
- required software and versions
- how services connect together
- required ports and configuration

Suggested improvement:
Add a shared “Prerequisites” section for the Kafka tutorial flow that includes:
- local Kafka setup instructions
- architecture overview
- environment requirements

Impact:
This gap makes the tutorial difficult to follow for beginners and blocks successful completion of the examples.

Note: I would be happy to contribute a PR implementing these improvements once the issue is reviewed.

Contributor guide

Open the contributing guide

Research direction

Start with the Kafka tutorial sequence at https://www.asyncapi.com/docs/tutorials/kafka and review the pages for consuming from Kafka, Avro Schema, Schema Registry, and Kafka bindings. Document a shared prerequisites section covering local Kafka setup, required software and versions, service connections, ports, and configuration; done means a beginner can run the examples from the tutorials.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, kafka
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.