[📑 Docs]: AsyncAPI Documentation is Frustrating

[zamu-flowerpot]

What Dev Docs changes are you proposing?

I know that this might come off as a rant or overly critical, but it is coming from a place of wanting to see this project succeed. I think this is a great project and love the open and inviting way that the documentation tries to bring people on to contribute.

---

Problem Statement

As an experienced developer, when I first encounter a new specification I want to get a quick overview with enough technical detail to know whether I should invest more time in the specification or not. With the AsyncAPI docs, I did not find the right level of information.

There was no clear and simple About page which explained in clear and concise language what the specification was, why it was useful, why it came about, and what it provides me compared to alternatives.

While it was easy to find the proper specification, without having a clear idea of how useful AsyncAPI is I think it's reasonable to not want to invest the time and read a proper RFC-2119 abiding specification.

While I eventually just started reading from the top, I felt like I was wasting my time on many of the pages. Eventually, I got fed up enough and decided to just read the specification anyways.

Frustrations

My view on documentation generally aligns with Divio's Documentation System where documentation can be broken down to a set of four categories which are the product of two axes (Practical-Theoretical and Learning-Doing) and align with how the reader will use the documentaiton. The four categories of documentation are: Tutorials (learning by going through the motions), How-To Guides (doing some goal by following a checklist), Explanations (enabling learning by reading theory and context), and References (enabling doing by reading description).

Of the four, I found that only the References section in the AsyncAPI matched my preconceived notions of where to find information in the documentation.

The Concepts section covered fundamentals which did not teach me anything about AsyncAPI itself on a conceptual level.

When I finally made it to Concepts/AsyncAPI Document sub-section, I thought it was just a weird bit that the background information wasn't grouped in its own section but blamed myself for not reading the headings and forcing myself to read background information. Instead I found reference material describing a YAML document adhering to AsyncAPI. Then the other pages in the sub-section were full of guides covering specific use cases.
Thinking I had missed something I started skipping around trying to figure out where I could find the illusive sales pitch of what AsyncAPI was and why use it. Frustrated I ended up reading the specification.

After I had read the actual specification, I wanted to kick the tires and I clicked on the tutorial section, then I found out that the Tutorial section actually had a bunch of conceptual stuff that would have been great to have in the Concept section!

Not to mention that I found that most if not all the "Overview" pages did not have content. Normally this wouldn't have bothered me, but by the time I was just clicking through pages trying to find information it was infuriating. Why have pages that provide no value to the reader? Worse, why name them overview!

Proposed Solutions

1. Have an about page that just talks about the AsyncAPI specification. Have it explain what it is, why it exists, why you would use it over alternatives, and where to learn more. Better yet, improve the current landing page!

2. Currently, the landing page for AsyncAPI is utterly devoid of information. There are a total of ten (10) sentences which mention AsyncAPI and they don't tell you anything other than AsyncAPI is an initiative and is related to Event Driven Architecture. I'm sorry to say this, but I don't think anyone will care about the initiative if the technical solutions it's pushing aren't clearly communicated. In contrast:

   • https://backstage.io/ has at least 7 sentences providing context to what Backstage is, why it exists, and why you would want to use it.
   • https://airflow.apache.org/ has at least 8 sentences that provide information about what it can do, the language it uses, and features it exposes.
   • https://kubernetes.io/ has 20(!) sentences that describe it clearly and provide context on its multitude of features.
   • https://capnproto.org/ has paragraphs of text and provides graphs, diagrams, and more explaining what it is and why you'd use it over alternatives.
   • https://serverlessworkflow.io/, another specification, has 3 sentences that provide me with enough context to know whether I want to read their entire spec.

3. Reorganize AsyncAPI documentation so that it is directly helpful. I don't think that AsyncAPI documentation content is bad or wrong, just poorly organized. Grouping the content based on how it will be used by the reader will help people learn about the specification and help them determine if the specification is helpful in their endeavors.

4. Remove any page that does not provide benefit directly to the reader. This is mainly a gripe caused with how every single overview page has almost no content regarding the technical specification.

Code of Conduct

• I agree to follow this project's Code of Conduct

[github-actions]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[derberg]

Thank you so so much for taking time to write down this issue and not only complaining but actually also providing recommendations, and also giving detailed information about what ain't done well.

For docs structure we follow https://diataxis.fr/ which seems similar to what you shared. But good to see Concepts are not fully covering the explanation side.

I personally think the biggest problem is the main landing page. I was actually complaining about it also few days ago during my presentation at AsyncAPI Conf on Tour.

Personally I think it should be simplified, few sentences that link you to another landing page that brings more details and introduces what I researched about real production case studies (my slides from conference
https://docs.google.com/presentation/d/1PRE93NDEWQn5W38bxm8Il_YEqWSu3msQ1Bmr0z09c9w/edit?usp=sharing) with explanation of real solutions powered by AsyncAPI spec.

You had a good timing with the issue creation!

[quetzalliwrites]

Hola @zamu-flowerpot, thank you for your extremely detailed feedback and proposed solutions! 😻 Your issue description is absolutely fantastic, providing us with much food for thought and ideas for action items moving forward.

Please also free to reach to me on AsyncAPI Slack if you need anything else for docs stuff.

[github-actions]

This issue has been automatically marked as stale because it has not had recent activity 😴

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience ❤️

[ParagGhatage]

Hi @derberg.
I was wondering if this issue is still open and in need of assistance. I’d be happy to start working on it if help is needed. Let me know!

[derberg]

@ParagGhatage at the moment we try to address the most important feedback about lack of easy explanation of what AsyncAPI can be used for. There is another issue that is related to a design work of landing page and probably more incoming changes

[ParagGhatage]

@derberg ,
Thanks for the update! If you need help with explaining AsyncAPI use cases or the landing page design, feel free to let me know—I’d be happy to assist.

[derberg]

sure @ParagGhatage , please join #3192 where @Mayaleeeee started working on desing