Improve Documentation Structure and Content

[Musilah]

Is your feature request related to a problem? Please describe.

Enhance the SuperMQ documentation by researching industry-standard documentation practices and integrating elements that align with our product needs.
This involves reviewing documentation from leading platforms to identify effective practices and incorporating placeholders for improved organization, user-friendly UI elements, examples, and links.

Describe the feature you are requesting, as well as the possible use case(s) for it.

1. Research and evaluate documentation structures and features from:

   • Watermill Documentation
   • Supabase Guides
   • PubNub Documentation
   • Ably Documentation

2. Identify and propose changes to improve our documentation structure and organisation.

3. Include UI screenshots and visual elements.

4. Create placeholders for proposed changes for future implementation.

Indicate the importance of this feature to you.

Must-have

Anything else?

Expected Outcome

• A detailed proposal with actionable suggestions for documentation improvements.
• Placeholder content that outlines how the documentation will look after enhancements.
• Clear prioritization of changes to align with the documentation roadmap.

[Musilah]

Supabase Documentation Overview

Supabase is an open-source Backend-as-a-Service (BaaS) platform that simplifies building and managing modern applications. It has features such as a PostgresSQL Database, authentication, real-time capailities using Websockets, Storage, Edge Functions and APIs.

This makes it quite similar to SuperMQ which means our documentation might have a lot more advantage in looking similar to it.

1. Homepage:

The Supabase homepage is clean and intuitive, leveraging card-based layouts to showcase:

• Core Products: Database, Auth, Storage, Realtime, and Edge Functions.
• Postgres Modules: Extensions like AI & Vectors, Cron Jobs, and Queues for advanced functionality.

It also has shortcuts that provide fast access to critical documentation pages for frameworks like React, Next.js, Flutter, Vue, and more. New users can get started quickly with clear links to tutorials, GitHub examples, and starter kits.

There is a pop-up at the bottom right of the screen that shows the specific launch details such as the version details, week since launch as well as a shortcut to the blogs containing all the new upgrades of the launch.

The footer shows the organisations contact support, a system status check as well as a link to the Changelog. The usual settings such as links to Social Media pages are the far right. Next to it are some links that lead to GitHub blobs for the Privacy Settings, Contributing, SupaSquad and Author Styleguide.

A dedicated modal allows toggling telemetry data collection as shown here:

2. Documentation:

The documentation itself feels like an extended landing page with a clear breakdown of sections and intuitive navigation. The Overview is an entry page that offers cards linking to documentation chapters, each with brief descriptions for easy browsing.

There is a Use cases section that provides practical examples with GitHub code samples to help first-time users quickly integrate Supabase into their projects.
Examples include:

• AI, Vectors, and Embeddings
• Subscription Payments (SaaS)
• Partner Gallery (Postgres full-text search, image storage, etc.)

When it comes to the individual docs pages, there is a rating system in the right sidebar. Each page can send back feedback from any user visiting the website.

Supabase documentation prioritizes a developer-friendly experience with:

• Clear, visually appealing cards for navigation.
• Easy-to-follow examples and framework-specific quickstarts.
• Interactive feedback tools and privacy settings to enhance usability.

We will get much needed inspiration from this for comprehensive and ease of navigation.

3. Blogs

Supabase blogs employ both a card-layout for the latest blog bringing attention to it and a table with all the previous blogs.

This approach works for a large number of blogs. Any new features added get dedicated blogs which have guides as well as samples. They also employ tags to assist in filtering.

[Musilah]

Ably Documentation Overview

Ably is a cloud-based platform that enables developers to create and manage realtime digital experiences without the complexities of scaling, latency, data integrity, and network outages. At its core, Ably operates as a publish/subscribe (pub/sub) Platform-as-a-Service (PaaS), ensuring that messages published by any device are received in realtime by all subscribing devices.

It bears some similar Key Features with SuperMQ such as:

• Pub/Sub messaging: This allows foe the efficient organisation and distribution of messages to multiple subscribers.
• Message History and Persistence : Much like SuperMQ Ably retains messages for a configurable duration, allowing clients to retrieve past messages and ensuring continuity even after brief disconnections
• Multi-Protocol Support : While SuperMQ supports HTTP, MQTT, WS and CoAP, Ably supports MQTT nad SSE

Some more features that Ably has include Push Notifications, Intergrations with various services and platforms such as Webhooks and AWS Lambda as well as Real Time Data Broadcast.

1. Homepage

The Alby homepage utilises cards as shown in the image below:

The cards serve as a centralized hub for developers to have quick access to services which include:

• Essential Core Services such as Pub/Sub, Spaces, LiveSync, Chat and Asset Tracking
• A comprehensive list of the SDKs that Ably provides
• A real-time System Status update on the operational status of Ably's services

Additionally, a chat pop-up powered by Inkeep allows users to ask queries directly.

FOOTER SECTION

The Footer section has some interesting features:

• A live indicator displaying Ably’s current operational status that also leads to their status site.
• Social Media Icons linking to platforms like Twitter, LinkedIn, GitHub and Stack Overflow at the far left.
• Links to cookies, legal documentation, data protection policies, and privacy information.

There are also distinct sections:

• Jump To : Quick links to key documentation pages, such as the Docs Home, Quickstart Guide, SDKs, and "What is Ably?" for new users.
• Explore : Contains links to live examples, tutorials, demos, change-logs, case studies, and FAQs to help developers and businesses understand and implement Ably's services.
• Tech Behind the APIs : Highlights Ably’s technical foundation with links to protocols, event-driven servers, whitepapers, and the "Four Pillars of Dependability" – emphasizing reliability and scalability.
• Company : Provides insights into Ably as an organization with links to the blog, pricing details, customer stories, and career opportunities, as well as contact information for inquiries.

HEADER SECTION

The Logo is to the top left which seems to be the convention. It also leads users back to homepage when clicked.
Key categories such as Products, Build, Manage, and Resources offer drop-down menus, guiding users to specific sections like APIs, demos, and tools
A prominent search bar allows users to find documentation, blogs, or solutions quickly.
There is also account management options for Log In or Sign Up.

CONS OF THE HOMEPAGE

1. The lack of a dark mode limits the themes preferences.
2. The lack of versioning limits the user's to read about only the current versions.
3. The lack of multilingual support limits accessibility to non-English speaking users.

2. Documentation

The documentation is structured into 5 key sections, with tabs located on the secondary topbar for quick navigation.
When the Pub/Sub card is clicked, it leads to a dedicated landing page that displays the key features of Pub/Sub as cards:

This is an interesting design and would work more if we grouped our chapters into larger groups of similar architectures and ensure they can each have their own landing pages with brief discussions.

The sidebar retains conventional documentation links such as:

• What is Ably?
• How to Use Ably
• Quickstart Guide
• SDK Setup
• Authentication

3. Blogs

There isn't really anything special about the Ably Blog. But it does have a different footer from the rest of the website.

[Musilah]

Pubnub Documentation Overview

Pubnub helps developers build, deliver, and manage real-time interactivity for web apps, mobile apps, and IoT devices. By providing a robust set of APIs and SDKs, PubNub facilitates the integration of real-time functionalities such as in-app chat, live audience engagement, multi-user collaboration, and IoT device control into applications.

In this way it is very similar to SuperMQ with its In-App Messaging, Access Manager, Functions and Events and Actions. From the website, it seems the docs and the products pages are different entities.

The PubNub homepage introduces its real-time communication platform, designed for building scalable and interactive applications across web, mobile, and IoT devices. Key features such as real-time messaging, presence detection, and integrations are prominently featured to showcase how PubNub supports in-app chat, live collaboration, and device synchronization. The page highlights customer use cases, developer tools, and the global infrastructure that ensures low latency and reliable message delivery for businesses of all sizes. This approach can be used for an official website page but I believe we already have one that is set up in a similar way.

From the products page we get brief overviews of each core feature.
Its core features include:

1. Publish/Subscribe Messaging: PubNub's Pub/Sub APIs allow for the rapid delivery of messages to single recipients or large audiences, ensuring low-latency communication essential for real-time interactions
2. Presence: This feature provides real-time awareness of user or device status, enabling functionalities like online indicators and occupancy counts, which are vital for collaborative applications.
3. Functions: PubNub Functions allow developers to execute custom code within PubNub's infrastructure, facilitating tasks such as message filtering, transformation, and integration with external APIs without the need for additional servers.
4. Mobile Push Notifications: PubNub integrates with services like APNs and FCM to deliver notifications to mobile devices, ensuring users receive timely updates even when the application is inactive.
5. Message Persistence: With storage and playback capabilities, PubNub retains messages for later retrieval, ensuring that users can access message history and that no data is lost during brief disconnections.
6. Access Management: PubNub's Access Manager provides fine-grained control over who can access specific channels or data, enhancing security and enabling the creation of private or restricted communication channels.

1. Homepage

The PubNub documentation homepage takes a simple and user-friendly approach to guide developers through its platform and APIs. It focuses on clarity and accessibility for users of all levels.

The homepage utilizes clean and minimal cards to direct developers on where to begin:

• Start Here: Quickly connect your application.
• Chat SDKs: Helps developers integrate live chat into new or existing applications.
• Core SDKs: Provides SDKs to integrate PubNub’s real-time services for various use cases.
• Publish Messages and Subscribe: Fundamental functionalities to interact with PubNub’s pub/sub model.
• Secure Your App: Highlights tools to ensure security and access management.

This is a much simpler approach that can be used for smaller documentation.

A prominent Search Bar is located at the center of the homepage, enabling users to search documentation quickly. Additionally, an AskAI feature assists developers by filtering queries and providing targeted results to improve search efficiency.

The header is simple and minimalist as well, with just the logo, account management and contact support.

The footer includes a Learn More section with four detailed categories:

• Demos: Explore real-time examples for features like chat, IoT, and geolocation.
• How-Tos: Understand core concepts and step-by-step processes.
• Tutorials: Detailed guides to walk through features and integrations.
• Live Code Tour: Interactive coding tour to familiarize developers with PubNub’s core features.

At the bottom, PubNub’s Privacy Policy link ensures transparency for users.

2. Documentation

The PubNub documentation Pages are also quite minimalistic and clean. The Left Sidebar displays all available chapters in a clear, collapsible format, allowing developers to jump to specific sections easily. The Right Sidebar highlights subtitles and key points within the current chapter, enabling quick navigation within the same page.

At the bottom left of the page, there is a toggle button for switching between light and dark modes. Although a useful feature, the placement is not immediately obvious and might benefit from a more prominent position.

PubNub provides a Network Status link at the bottom left, which redirects users to their current status page. This ensures transparency and allows developers to check for any service disruptions or ongoing issues.

An Ask AI Search Bar is positioned at the bottom right, the Ask AI tool allows users to filter queries and get targeted answers to documentation-related questions.

3. Blog

The Blogs Pages also use the same clean and simple approach with cards with titles and short descriptions.

The Card-Based Layout shows each blog post as a card with:

• A title for the post.
• A short description summarizing the content.
• Relevant categories such as How-to, Insights, Product Updates, etc.
• The author name and publication date are displayed for transparency.

Located at the top of the blog page, filters allow users to refine their reading experience. The blog features a mix of technical guides, product updates, and insightful articles relevant to real-time applications, helping developers stay informed.

The footer of the blog page has shortcuts to essential resources.

• Company :- About Us, Pricing, Careers
• Support :- Contact Sales, Documentation, Network Status
• Additional Resources :- Product Updates, Guides, Insights

At the bottom right, the Ask AI feature remains available to provide assistance and answer specific queries.

[Musilah]

Watermill Documentation Overview

Watermill is an open-source library designed for building event-driven applications.

Watermill focuses on flexibility and performance, enabling developers to connect with various messaging systems like Kafka, RabbitMQ, and Google Cloud Pub/Sub.

Here are its core features:

1. Ease of Use: Watermill is designed to be easy to understand and implement, even for junior developers.
2. Universality: Supports various architectures, including CQRS, Event Sourcing, and streaming systems. Integrates seamlessly with messaging systems like Kafka and PostgreSQL.
3. High Performance: Optimized to process hundreds of thousands of messages per second, ensuring high scalability.
4. Flexibility: It works with different transports and brokers, enabling the use of modern tools such as Kafka, Google Cloud Pub/Sub, and RabbitMQ.
5. Extensibility: Developers can extend and adapt Watermill to meet their specific needs.

1. Homepage

The homepage of Watermill is minimalistic and clean as well, focusing on a developer-friendly design.

The Hero features the Watermill logo and mascot with a welcoming tagline: "Building event-driven applications the easy way in Go" as well as two primary call-to-action buttons: Get Started and See on GitHub.
Much like SuperMQ three prominent cards highlight Watermill's core strengths:

• Easy to Use: Watermill's straightforward learning curve.
• Universal: Support for event-driven architectures like CQRS and Event Sourcing.
• Fast: Designed for high throughput, processing thousands of messages per second.

The Header Section includes these features:

• Navigation Links: Docs, Examples, and Support.
• A GitHub button displaying the project’s star count.
• Icons for search, theme toggle (light/dark mode), and GitHub access.

While the footer is minimal or nearly absent, aligning with the clean and simple design. There is only another instance of the logo taking up much of the lower area space with another link to the documentation.

2. Documentation Structure

The Watermill documentation at Getting Started follows a developer-centered layout, ensuring a smooth experience for readers.

The left sidebar lists all documentation chapters. Much like the Docusaurus documentation default the content is also clean, well-organised and text-heavy. The right sidebar only has the sections in each chapter.

3. Blog Pages

While the Watermill website does not host its own blogs, they can be found at the Three Dots Labs.
The blogs also follow a similar outlook to SuperMQ.

This seems to be the simplest format and what we can go for when it comes to our blogs. There will be a series section as well as a popular section and a whole list of tags the user can go through to find what they would like much easier.

[Musilah]

Proposed Layouts for the Homepage:

Layout #1

This employs a centralised Hero Section that will match SuperMQ default color.
The cards will showcase different products provided by SuperMQ.
They could also feature the core features of the platform instead much like what we already have.

The lower section will feature our SDK's and UI repos with links blogs about the SDKs as well as links to the UI Docs.

For the Footer we can have a GoLang centered Logo, Blogs and Support and Contact information.

Layout #2

The *Her Section will instead take up the whole area giving a much more compact and boxy appearance.

The cards content feature major sections from our docs eg:

• The Overview
• Quick Start
• Development Tools
• Extensions

Each card will include a small description.

The Footer will then have a Learn More section with our blogs, samples, demos and examples.

Proposed Layouts for the Documentation pages

Layout #1

This shows the basic layout we currently have since this seems to pass the convention.

Layout #2

This shows a Landing Page which will have the products from HomePage 2. It will have brief descriptions for each section. The cards will then link to section specific layouts as shown in Layout #3.