docs: design new docs overview homepage

[quetzalliwrites]

Proposal

This issue stems from the earlier proposal already underway of changing the Information Architecture (IA) of our Docs, as filed in #350. These IA changes imply a gradual rollout of changes to the main website's navigation items related to Docs, complete content overhaul/repurposing of the current Docs, and UI design improvements for these changes. It also means new URL structure rollout and 301 work, which is already filed and being tracked via #459. For this issue, I wanted to focus on the design efforts required for ADDING a new Docs /Overview homepage.

I want to team w/ @mcturco on designing a new AsyncAPI Docs overview homepage because we currently lack one.

(The current user experience immediately lands you on an intro tutorial for getting started building your first asyncAPI document, but there is no actual 'homepage' for the Docs.)

I have made a rough figma framework to showcase visually how I think it could be done:

Description

Changes introduced:

• add new overview page
• designing new page as Docs 'homepage'
• showcase cards that tell users about what content buckets our docs are divided into (like attached sample img proposed above)
• new design and copy for entire page
• using the new branding colors from @mcturco's brand refresh

Are other Docs designing theirs like this?

Here is an OSS example:

• https://www.gatsbyjs.com/docs/

Here is another docs overview homepage example that is not OSS, but has similar design elements that I hoped to show to Missy:

• https://vercel.com/docs

[mcturco]

I think this is a great idea! Just to confirm, you are talking about adding a page to replace this one or to be added above it/before it? I think that this page does give a good introduction but is very wordy, so I would love to use your new proposed template to come up with some ideas.

Love the examples! I think the Gatsby one is nice, but we could probably come up with a more digestible layout! And I like the UI of the Vercel docs but I think we need to add more visuals (like the diagram that you are proposing to add at the top)

I think the biggest thing that we need to do at this point is figure out all the content that we want to have on this page and then we can maybe come up with different ways to organize it visually from there, but I like the content buckets that you have in your mock up!

[whiteHatpro]

@alequetzalli is anyone working on it?

[quetzalliwrites]

@alequetzalli is anyone working on it?

Yes, @mcturco and I are both on this. Are you interested in helping contribute to design it with @mcturco? 🙃

[quetzalliwrites]

I have created a new Docs issue to handle the diagram proposal separately:
#518

[quetzalliwrites]

Had a chance to think this over more and discuss it with a few other community members (Missy, Fran, Lukasz). We identified further context we needed to add to this issue and even identified new ideas. This comment attempts to encapsulate this further.

FIRST, the following is the NEW proposed content outline changes to the Docs' left-hand navigation:

• Overview
• Concepts
  • Producer
  • Consumer
  • Traits
  • Bindings
  • Channels
  • etc.
• Tutorials
  • Create AsyncAPI document
  • Create streetlights app
  • Using Kafka protocol
  • Using WebSocket protocol
  • etc.
• Tools
  • Modelina
  • Studio
  • Parser
  • etc.
• How-To Guides
  • Reusing schema definitions from OpenAPI files within AsyncAPI files
  • etc
• Reference
  • API spec
  • CLI

SECOND, Since we're already invested in utilizing the Diátaxis methodology for determining our content buckets (Concepts, Tutorials, Tools, How-To Guides, Reference), it makes sense to ADD NEW landing pages to introduce each content bucket. (This proposal came from @mcturco.) Each landing page introducing each content bucket would include welcoming copy introducing the user to the learning paths available under this content bucket. This also means that we would now have the following NEW URLS:

• asyncapi.com/docs/concepts
• asyncapi.com/docs/tutorials
• asyncapi.com/docs/tools
• asyncapi.com/docs/how-to-guides
• asyncapi.com/docs/reference

THIRD, to build on the last proposal, each content bucket landing page could include cards featuring content the community has already requested but that we still need contributions for. Instead of having a card that merely says "coming soon," we could have the cards read, "Contributors Needed." 😀 (This proposal came from @derberg.)

Using the example of the /Tutorials landing page, we already know we would want to add cards encouraging the following tutorial contributions:

• Kafka tutorial
• WebSocket tutorial

---

@mcturco, is there anything missing here or that you need from my end to get us started for this? 🤔 Just let me know. 😄

[boyney123]

Sounds great @alequetzalli.

Just a random thought but part of the tutorials, I wonder (at some point, maybe not straight away!) if we could spike/explore making interactive tutorials (that are not behind some login system like we have now), that we could embed on our website.

For example we could look at things like Sandpack and prob come up with a nice way to allow people to follow things and learn.... Just a thought! (as I said not for now, but it would be good to get there I think anyway).....

[quetzalliwrites]

Just a random thought but part of the tutorials, I wonder (at some point, maybe not straight away!) if we could spike/explore making interactive tutorials (that are not behind some login system like we have now), that we could embed on our website.

Yes, I completely agree with you that adding interaction in learning is amazing. When we are ready to explore doing that for our open source project, the place to put interactive learning would be on a learning platform versus the documentation section. 🙂

I actually just ended up researching this recently and that's why identified this solution is how it's covered in the industry.

[mcturco]

@alequetzalli I think you nailed everything that we talked about, thanks for taking the time to write that all out!!! 💪 I think we have enough here to get started on a mock up, so I can start working on that! I think for now until we get more feedback in the separate issue for the "fancy diagram" 😆 I am going to use a placeholder box for that.

[mcturco]

Hi! Popping in here to share a prototype I put together to show the first iteration of the new overview page for the docs. Would love some feedback/ideas on this! Please note that the visualization diagram is still drafted as we are waiting on more feedback for ideas for that in this separate issue.

Here is the prototype link: https://www.figma.com/proto/vPO7Go2C0v609Xw2L8eWS8/Website?page-id=3%3A114&node-id=11%3A218&viewport=241%2C48%2C0.5&scaling=min-zoom&starting-point-node-id=11%3A218

cc: @alequetzalli

[quetzalliwrites]

Hey @mcturco !! :) omg, the body of the page is sooo lovely and 💯 an improvement on what is currently there ❤️✨✨

Question, I thought you wanted to incorporate the updated outline based on the new content buckets, and hence me writing them in the comment here for you? 😄

[mcturco]

@alequetzalli Yay! Thanks! And whoops! I definitely only added the new Overview link and completely forgot to update the others. I can do that real quick! Thanks for the heads up 😄

[quetzalliwrites]

🙊

[mcturco]

Okay all updated! @alequetzalli

[quetzalliwrites]

@mcturco thank you!!!

I love it! I love how your prototype shows two diagrams at top, the way you showed the main content buckets in those cards past the fold, and the style is nice!

Thank you so much!!!

What do you think are the next steps for this? 😀 🤔

[derberg]

Looks great from my point of view 🥂

I know this issue is about design, but just to clarify, under Reference we should have the current specification

[mcturco]

@alequetzalli Hooray!! glad you like it 😄

Unless anyone has other feedback for the layout & design, I think we can move forward with this one and write some content for the placeholder text while we are still waiting for feedback on what the diagram should look like.

Here's the breakdown of copy we will need based on this design in case that's easier to reference other than looking at the design mockup:

• Welcome copy (about 2 sentences) Introduces us to the docs
• Diagram/Animation copy (1 sentence for each of the following) *We can probably hold on this one until we have a solid direction for the diagram design
  • "current EDA workflow"
  • "using AsyncAPI in your workflow"
• Content buckets copy (1 sentence for each of the following)
  • Concepts
  • Tutorials
  • Tools
  • Reference
• CTA content section (about 2 sentences)
  I really only included this because I thought that we needed something else on that page, so I figured it was a good opportunity to take the user to a specific page that we don't want them to miss. Maybe this goes right into the How-to guide? So the title could be something like: "Ready to get your hands dirty?" and then some supporting copy to lead them to click the button. Just a thought! I definitely would love to hear what you think on that.

@alequetzalli would you want to spearhead the copywriting? I could help write some stuff as well but you're the expert in that area!! 😄

Other questions that I have: would we be waiting to ship this until we have docs written for all other areas? We definitely don't have to rush into anything, just trying to get a look into what the timeline goals are for this project 👍

I think in the development phase I would love to set up some event tracking on this page so we can measure where most people are going first which can help with iterating on the design in the future! ✨

[mcturco]

I know this issue is about design, but just to clarify, under Reference we should have the current specification

@alequetzalli turning to you to address this one as I think it relates to your new way of organizing the docs

[quetzalliwrites]

I know this issue is about design, but just to clarify, under Reference we should have the current specification
@mcturco @derberg

Yes, this is only for design so don't take any of the outline elements as part of the TW work set in stone. This is just better than using lorem ipsum.

[quetzalliwrites]

Unless anyone has other feedback for the layout & design, I think we can move forward with this one and write some content for the placeholder text while we are still waiting for feedback on what the diagram should look like.

Yes, I will contribute the technical copy needed for the Doc's HomePage. I actually plan to do that after the design of the page layout and diagrams are determined/finalized by you, because I need to know what we're going with before I can really pick that up. 🙂

Other questions that I have: would we be waiting to ship this until we have docs written for all other areas? We definitely don't have to rush into anything, just trying to get a look into what the timeline goals are for this project 👍

So I will be making this change in the SAME Pull Request as the one for covering issue #350. I will only use 1 PR because our Docs is currently tiny enough to not require a more granular approach.

I know you ask for a timeline.. so basically, I will pick write copy for this new page once the design phase is finalized, and I can continue working on #350 while/until you wrap up the design for this one. 🙂 I currently (on my plate) have this issue prioritized again, so it's what I am working on for 2022 Q1. 😄

I think in the development phase I would love to set up some event tracking on this page so we can measure where most people are going first which can help with iterating on the design in the future! ✨

Sure! I bet you'll learn good things, please share when you do! ✨✨✨

Are you contributing the development phase? or who do you think we should tag for that part? I was just going to add the website code owners to website and see who bites. 😄

[quetzalliwrites]

Yo again, @magicmatatjahu, @mcturco, @derberg:

This is the PR where we are adding a NEW /Homepage for our Docs. The new /Homepage has already been designed by @mcturco and her prototype can be seen here.

The Problem

I need Development help adding the Explore the spec section to the NEW /Overview homepage page I have created via PR #601 and that can be seen in this preview link.

I don't know how to add the 4 cards components.

The contributor ask

I was talking about this with @derberg this week and he recommended we tag @magicmatatjahu for the development work.

@magicmatatjahu, since @mcturco already gave us Design guidance via her prototype, can you help us with the Development work?

[quetzalliwrites]

Hey @magicmatatjahu, tagging you again in this issue because I think you may have missed the notification. 🌟

[magicmatatjahu]

@alequetzalli Yeah sorry, I miss that notification 😅 Of course I can do that! Give me some time :) To Monday it should be done.

[magicmatatjahu]

@alequetzalli #601 (comment) 😉

[quetzalliwrites]

@alequetzalli #601 (comment) 😉

@magicmatatjahu Thanks for the tagging!! Replied! 🥳