docs(readme): overhaul README with visual assets, Docker quick-start, and storytelling#5
Merged
electricalgorithm merged 3 commits intomainfrom Feb 24, 2026
Merged
Conversation
…lling Rewrite the README to tell a compelling story about why ProtoMQ exists and what makes it useful for IoT/edge deployments: - New tagline emphasizing MQTT + Protobuf + Zig synergy - Added SVG payload comparison chart (JSON vs Protobuf, 3 scenarios) - Added SVG terminal demo showing the publish/subscribe workflow - Mermaid architecture diagram of the broker internals - Reframed performance benchmarks with context - Docker quick-start with Dockerfile and docker-compose.yml - Condensed Service Discovery and Admin Server sections - Navigation links and FAQ reference - Added .blog/ to .gitignore for draft social media posts Signed-off-by: Gyokhan Kochmarla <gokhan.kocmarli@gmail.com>
- Replace Mermaid architecture diagram with 'Under the Hood' section highlighting epoll/kqueue, zero deps, runtime schema registry, single allocator, comptime tables, and cross-compilation - Use h3 headers instead of h2 to reduce visual noise - Remove Resources, License, and standalone Service Discovery sections - Condense Admin Server to a one-line mention with link to FEATURES.md - Rewrite 'Why ProtoMQ' in a more conversational tone - Move detailed Service Discovery and Admin Server docs to FEATURES.md Signed-off-by: Gyokhan Kochmarla <gokhan.kocmarli@gmail.com>
…-to-Protobuf The broker only accepts Protobuf payloads on the wire. The CLI has a --json convenience flag that encodes to Protobuf client-side before publishing, but the protocol itself is Protobuf-only. The previous wording incorrectly implied the broker does JSON-to-Protobuf conversion. Signed-off-by: Gyokhan Kochmarla <gokhan.kocmarli@gmail.com>
electricalgorithm
force-pushed
the
docs/readme-overhaul
branch
from
6e2a66e to
65cd939
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What this PR does
Rewrites the README to address feedback about the project being too technically descriptive without explaining why ProtoMQ matters. The new README tells a story aimed at developers evaluating the project for the first time.
Changes
New README structure:
docker compose up— one command to try it)New files:
Dockerfile— multi-stage Alpine build with Zig 0.15.2docker-compose.yml— single-service compose for one-command demoassets/payload_comparison.svg— bar chart comparing JSON vs Protobuf payload sizesassets/terminal_demo.svg— terminal mock showing the publish/subscribe workflow.gitignore— added.blog/for draft social media posts (not in this PR)Why
The original README listed features but did not explain the problem ProtoMQ solves or why someone should choose it over plain MQTT + JSON. The feedback was that developers on HackerNews/Reddit would scroll past "fast MQ" but stop for "74% bandwidth reduction on IoT sensor data."
Screenshots
The SVG assets render directly on GitHub. Preview by viewing the README on the branch.
Testing
docker build -t protomq-test .