bump-sh / docs Goto Github PK

From a reader's perspective

For now when browsing any of the three categories “Documentation”, “Product updates” or “Guides”, as a reader I don't know in which of these categories I am.

My thoughts on how to solve

In the Documentation, we have a sidebar which helps to navigate and understand we are in the same “space”. So it's kind of ok.

But in both the “product updates” and “Guides” category, the reader doesn't really know where he is. In my opinion that's because of two reasons:

• We could highlight the category in the top nav bar

  I'm thinking of something like:
  

• We could have a breadcrumb below the top nav bar:

  • in case of the “product updates” it could be a date/time slider for example
  • in case of the “Guides” it could be the main categories (which we already have in the home page of guides, but loose when reading an article)
    

It would be great to find a name for the content hub that:

• is easy and short as a URL (like rapidapi.com/learn)
• is explicit
• contains a pun/nod to the API world
• helps for SEO

Ideas welcome!

Current ideas list (not necessarily compatible with all requirements above):

• bump.sh/learn
• bump.sh/resources
• bump.sh/get (ref to the GET verb, works well with bump.sh/get/help, and with future API catalog listings: bump.sh/get/public-apis/twilio)
• bump.sh/keys Naming our Content Hub {API:Keys} could be an interesting one, looking at the count of monthly searches for the api key keywords and the relatively low cost for that keyword (see image below). It's also rather easy to make jokes about Bump that give you the keys to API knowledge, and so on.

All guides have the same "last update date".

For instance, this one hasn't had an update since a very long time, but the page says it was today
https://docs.bump.sh/guides/api-basics/api-architecture-diagrams/

(redacted)

We want to give a quick access for our content hub visitors to the following resources, via the top nav bar.

• Go to Bump.sh (as a visitor)/go to the user dashboard (as a user)
• Sign-in/sign-up (can we know if the user is signed in?)
• Go to the Bump.sh API reference doc.

This also requires some design, to avoid rendering as below:

Related to #215. I don't know what the limitations would be, but it would be great to have a view of "what's new" in the guides and potentially "what's been updated lately."

We're starting to have a decent amount of guides, and for our returning readers, it would be great to know quickly what is the freshest content by:

• seeing a "New" tag for a guide that has been initially published in the last 4 weeks
• (if possible, although less important) seeing an "Updated" tag for a guide which has been updated in the last 4 weeks. Worst case scenario, we can fallback on updating the prefix in the filename only for major updates of guides, and consider them as "New".
• having a list view of all "New" guides

Current Behavior

Right now, the search in the hub content displays a list of result without a lot of context (only a title and an excerpt) as seen below:

Ideas on potential future behavior

• It would be really nice if the items of the results are grouped by section (Documentation, Product Update or Guides), or if we add a visual label, or whatever other nice UI trick to quickly identify which result comes from which section.

• Ideally, the groups order would depend on which page we are in (if the user visits a documentation page, the “Documentation” section of search results should be displayed first)

https://github.com/bump-sh/docs/blob/main/src/_guides/api-basics/api-architecture-diagrams.md?plain=1#L4
https://docs.bump.sh/guides/api-basics/api-architecture-diagrams/

When importing the content, I saw several issues with images:

• some are super old, showing an old version of the product
• their size and style aren't consistent
• some are displayed super weird

We should do a global check and at least replace the oldest/ugliest one, WDYT @jayk-u?

We want to let user chat with us on the Help center pages, via Intercom.

By default, the Intercom icon (usually located at the bottom right part of the page) should not be displayed.

The chat will open upon user request (click on the icon planned in #17)

Inspiration sources:
https://segment.com/docs/ (thank you @scharrier ❤️)
https://rapidapi.com/learn
https://docusaurus.io/showcase

• https://docs.dyte.io/
• https://developer.redis.com/
• https://refine.dev/ (menus)
• https://hub.qovery.com/

As Docusaurus works as a single-page app, we only receive /help URL calls in analytics. We need to find a way to get the "page change" event and send a call to Fathom.

Meilisearch? Algolia?

Here are the required feature for hosting the content hub:

• custom domain support
• https support
• URL rewriting server side (from config)

Here are nice-to-have ones:

• Preview on PRs (= 1 URL per PR on which we can preview the future rendering. Note that it shouldn't be indexed by SEs)

I'd like to have the main landing page of the content hub route users to various sections. Like on Docusaurus' site

Sections:

• the blog (already imported in #1)
• the help center (to be imported from Gitbook)
• the API doc (TBD how to integrate it: 1st step as an external link, second step via a plugin development)
• the tutorials (which will contain for instance the draft.dev articles, and further articles/content we'll create with Valériane)

A design like https://rapidapi.com/learn for the main landing page would be great.
The same design for our own /hub/tutorials so that we can dispatch people to tutorials focused on OpenAPI, or on AsyncAPI, or on generic API knowledge would be great.
Each section will have its own sidebar/table of contents.

Projected structure:

Content Hub Landing                 # Global landing page design
├── Bump.sh API reference.          # Ideally integrated from Bump.sh
├── Help Center
│   └── What is Bump.sh?
│   ├── Specifications support      # Doc group in the table of content, not an actual page (see Gitbook)
│   │   └── AsyncAPI support
│   │   └── OpenAPI support
│   │   └── Polymorphism
│   ├── Getting up and running.     # Doc group
│   │   └── Bump.sh CLI
│   │   └── Continuous Integration
│   │     └── GitHub Action
│   │   └── API Change Management
│   │     └── WebHooks
│   │   └── Branching
│   │   └── References
│   │   └── Hubs
│   ├── Customizing your docs      # Doc group
│   │   └── Set a customer domain
│   │   └── Meta images
│   │   └── Markdown support
│   ├── Configuring access         # Doc group
│   │   └── Organizations
│   │     └── Single Sign-On (SSO)
│   │   └── Access Management
├── API Guides                      # Global landing page design
│   └── API Basics
│   │   └── Introduction
│   │   └── The Best API Documentation Tools for Dev Teams
│   │   └── A Developer's Guide to API First Design
│   │   └── Creating Better API Architecture Diagrams
│   └── OpenAPI
│   │   └── Introduction
│   │   └── Building a REST API with OpenAPI and Typescript
│   │   └── Using OpenAPI Tags to Better Organize API Endpoints
│   │   └── Using OpenAPI Tags to Better Organize API Endpoints
│   │   └── Building an ExpressJS API with OpenAPI
│   │   └── Using OpenAPI Security schemes to describe your API authentication
│   └── AsyncAPI
│   │   └── Introduction
│   │   └── AsyncAPI Example: Building Your First Event-Driven API
│   │   └── AsyncAPI vs. OpenAPI: Deciding Which Specification is Right for Your App
│   │   └── AsyncAPI + Websocket Example Application
│   │   └── AsyncAPI + Kafka Example Application
└── Changelog

In a later step, the Content Hub could also gather the catalog of public APIs imported to Bump.sh as a dedicated section:

Content Hub Landing                 
├── Bump.sh API reference.
├── Help Center
├── Tutorials
├── Public APIs Catalog           # Specific landing page design focused on API doc search
└── Blog

Currently, it's possible to click on "edit this page" on our pages:

Segment.io has a nice version of this.

We don't need all of it, and for now would start with the sections:

• Need support? (text + one button to send an email, and one to open the Intercom chat)
• Give the possibility to open an issue or a PR, and add design to the existing link

The Huma guide has some rendering issues with number lists resetting to 1 after a code block. it should continue with the number provided.

The Fast API guide has the same issue.

It would be great to be able to click on images and screenshot to get them bigger, with a blurry/darken background for lisibility.
Just noticed while working on help center that would be a nice addition as some screenshots could be a bit hard to read.