Suggestion For Improving The Documentation

[RubenvanderHout]

Suggestions for Improving the Documentation

I recently found Brighter and it seems like a good library for messaging. However I found the documentation confusing. I looked online to see if others had similar issues and came across this post asking for suggestions. So i want to share my thoughts on improving the documentation.

I don’t think the issue lies with the information in the documentation. The main problem seems to be its organization. Brighter documentation mixes different types of information. I don’t always need a complete explanation sometimes i just want to get started.

I suggest clarifying the structure between what the reader wants to do and the documentation. One effective approach i found is Diátaxis. It categorizes documentation into four sections based on what the reader wants to achieve:

• Learn something new
• Complete a specific task
• Look up technical details
• Understand why something works the way it does

I believe this could make the existing documentation easier to navigate.

Diátaxis

Tutorials

Tutorials should help new users learn Brighter step by step. These should be the first things users see when they start with the project.

Examples:

• Creating a simple Web API using Brighter for messaging
• Sending your first command/event/message
• Building a complete messaging flow with multiple microservices

How-To

How-to guides should focus on solving specific problems users face.

Examples:

• How to configure Brighter with PostgreSQL for both transport and outbox
• How to configure Brighter with RabbitMQ

Reference

Reference documentation should contain precise technical information about the API, similar to how Microsoft's documentation organizes API references.

Explanation

This section should focus on explaining the "why" behind the project. Existing documentation like Under The Hood would fit well here.

This section could explain:

• How Brighter works internally
• Why certain design decisions were made
• The trade-offs behind those decisions

I hope this feedback is helpful. I believe it will make the project easier to understand and use for future users.

[iancooper]

Hi @RubenvanderHout -

Thanks for that. These are great suggestions, and thanks for taking the time to share your feedback. I'll look over them and see what we can do.

[iancooper]

@RubenvanderHout — following up on this properly. I've audited the docs against your suggestions and written up five specifications covering the work. They're in #72 if you'd like to follow along or push back on any of it.

Your central point holds up: the information is mostly there, the organisation isn't. A few things the audit turned up that made the case sharper than I expected:

• There is no tutorial at all. Our "Overview" section is a code showcase (which literally opens by saying "It's not about how... It's not about why"), a glossary, and a philosophy piece. Nowhere do we say "do these seven things and you'll have something running." That's exactly your "sometimes I just want to get started."
• Transports are filed under a delivery guarantee. RabbitMQ, Kafka, SNS/SQS and Azure Service Bus all sit under a section called "Guaranteed At Least Once" — accurate, and a useless signpost if you're looking for "how do I use Brighter with Kafka".
• Pages mix all four modes internally. Our RabbitMQ page interleaves reference, explanation, a how-to and best practices across 565 lines. To find the subscription parameter list you have to read an essay on quorum queue trade-offs first.
• Two glossaries, and a "Reference" section containing exactly one page.

The plan:

Spec	What
009	Tutorials — a four-rung ladder: in-process command → first message over RabbitMQ → durable Postgres Outbox → Kafka
010	Information architecture — restructure the table of contents around reader intent, with redirects so existing links keep working
011	Page-type discipline — every page declares what it is; split the pages that mix modes
012	Reference — consistent option tables (name / type / default / description), verified against source automatically rather than by hand
013	How-to guides — task-phrased recipes

Two places where I've deviated from a literal reading of Diátaxis, in case you disagree:

Not using the four modes as top-level navigation. A purist split would turn each technology into four pages, across 7 transports, 8 outboxes, 6 inboxes, 7 schedulers and 7 distributed locks. People navigate that material by technology — "I'm on Kafka" — and want configuration and gotchas together. So those families stay grouped by technology, and the four-mode discipline is applied within pages instead. Diátaxis as an authoring rule rather than a filing rule.

Your Reference example names two different things. Microsoft's API browser is generated from source XML comments — that belongs in the Brighter code repository, and it's a separate initiative. What we're doing here is prose configuration reference: the options you actually set, with types and defaults. My read is that's what most people asking for "reference" actually want, but say so if you meant the generated kind.

Your PostgreSQL-for-both-transport-and-outbox example is in the first batch of how-to guides — it's a good catch, because it's fully supported, entirely reasonable to want, and there is currently no page for it. You have to find two separate pages and work out that they compose.

Thanks again for taking the time to write this up, and for pointing at Diátaxis specifically — having shared vocabulary for "these are four different things and we're blending them" made the problem much easier to describe.