Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: case studies content setup #921

Merged
merged 44 commits into from
Mar 20, 2023
Merged

Conversation

derberg
Copy link
Member

@derberg derberg commented Aug 30, 2022

Related to asyncapi/community#187
UI related to #1008

This is a proposal on how I would like us to start collecting case studies/use cases that entire AsyncAPI community could benefit from:

Contents of this PR:

  • example case study based on a case study from Adeo. Andoine from Adeo made sure we can make it official, and @M3lkior made sure technically all is correct.
  • template for future case studies
  • json schema for case study YAML validation
  • very simplistic UI to make it easier for designers to come up with better, future version, with filters and nice table of contents maybe. With review please focus on what can be improved just with current proposal, not what can be added. From my perspective what is critical is the content and simple UI. Filters, table of contents, and other stuff, like additional views, can be added later by other contributors.

tl;dr the idea is:

  • to collect all the data in a form of YAML 😉
  • allow official and anonymous source
  • for people that cannot work with YAML we would also have casestudy_template.yml in a form of GitHub issue template (in spec repo) and then volunteers would make sure to transform it into YAML in website repo

Why YAML?

  • So we can do UIs that will make it super easy to collect specific information. Examples:
    • Someone proposes we introduce a change in kafka bindings. With one click in UI we could filter out real production use cases of kafka bindings, see how these are used, and also ping owners of use cases to have a look at proposed changes
    • Devs want to work on tools for editing AsyncAPI files, and with easy filter out, they can get a list of explanations by the company on how they work with file editing, if they use some IDE or other tools
    • We can have one UI where we just list case studies and also a separate UI where we list use cases. Where readers do not care what a specific company is doing with AsyncAPI but what people, in general, do with AsyncAPI. Long term, when we have many different use cases, we can modify YAML to have use case categories, so in UI, we can even filter by documentation or other.
  • It's about having structured information that is easy to read and present clearly in UI.

Important to remember is that this YAML is just the first version. We can, of course, extend it and modify it as much as we can over time. This is just the initial version based on the first case study.

Vision
With a standard way of case study info structure, it should be super easy for anyone to collect case studies and submit them as PR to website repo. We start with 1 case study and in a year from now we have 50 ❤️


Please have a look, and share your opinion. What could be fixed/improved here?

Pinging participants of asyncapi/community#187 and possible interested folks
@nictownsend @abelgomez @jessemenning @Ugbot @fmvilas @alequetzalli @magicmatatjahu @smoya @jonaslagoni


Stuff for later, that I want to leave for contributors to work on is:

  • workflow that checks on PR level if YAML is valid against the schema
  • TOC in case study to enable easier navigation
  • Remove hardcodes from components
  • Add filters for list of case studies
  • Enable alternative views, where you can just list all use cases fields in a list, or only example AsyncAPI documents, to make information easy to access
  • And probably much more 😄

@netlify
Copy link

netlify bot commented Aug 30, 2022

Deploy Preview for asyncapi-website ready!

Name Link
🔨 Latest commit 183107e
🔍 Latest deploy log https://app.netlify.com/sites/asyncapi-website/deploys/641842fb2958750008b09a59
😎 Deploy Preview https://deploy-preview-921--asyncapi-website.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

@derberg derberg marked this pull request as draft August 30, 2022 14:44
@github-actions
Copy link

github-actions bot commented Aug 30, 2022

⚡️ Lighthouse report for the changes in this PR:

Category Score
🔴 Performance 45
🟠 Accessibility 88
🟢 Best practices 100
🟢 SEO 100
🔴 PWA 30

Lighthouse ran on https://deploy-preview-921--asyncapi-website.netlify.app/

public/casestudies/adeo.yml Outdated Show resolved Hide resolved
public/casestudies/adeo.yml Outdated Show resolved Hide resolved
public/casestudies/adeo.yml Outdated Show resolved Hide resolved
public/casestudies/adeo.yml Outdated Show resolved Hide resolved
@derberg
Copy link
Member Author

derberg commented Sep 7, 2022

added some updates to Adeo case study

major stuff that is missing are examples, but they just need some prep work before they are shared publicly

@M3lkior
Copy link

M3lkior commented Sep 8, 2022

@derberg my gift for you: https://gist.github.com/M3lkior/6b9ce2275f32018eebaf9e9f8cd67910

Enjoy and let me know if it is what you expect !

@derberg
Copy link
Member Author

derberg commented Sep 8, 2022

@M3lkior it is perfect, I already update the PR with all the examples

I think you can start review if I did not write anything wrong.
The only thing that is missing is the contact. I wrote to you in slack about it

Copy link

@M3lkior M3lkior left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

an you link to me the path of the case studies page on the deploy-preview website ? i don't find it on https://deploy-preview-921--asyncapi-website.netlify.app/

public/casestudies/adeo.yml Outdated Show resolved Hide resolved
public/casestudies/adeo.yml Outdated Show resolved Hide resolved
public/casestudies/adeo.yml Outdated Show resolved Hide resolved
public/casestudies/adeo.yml Outdated Show resolved Hide resolved
@M3lkior
Copy link

M3lkior commented Mar 16, 2023

Sorry, I didn't push anything as I didn't get time to work on it. Can you wait for 1-2 days to merge this PR?

sure man @akshatnema , no worries

Sorry, I can't approve if I don't think it makes sense 💜

well I definitely get your point. Let's iterate again with other owners to have individual nav element there

@fmvilas @derberg @mcturco @akshatnema @magicmatatjahu

can you have a look, IMHO it really makes sense to have a case study as an individual element in the top nav. We can eliminate Jobs that are not used by anyone.

Screenshot 2023-03-14 at 19 35 15

I think Docs and Tools needs to stay in their current positions. Maybe we can remove the job section and add the case studies section before the Blog section ?

@fmvilas
Copy link
Member

fmvilas commented Mar 16, 2023

IMHO it should be in the top navigation. I’d remove Jobs and put it on the footer. The order that I like is Docs, Tools, Community, Case Studies, and Roadmap.

Please, before you merge any change, take into account that “Case Studies” is larger than “Jobs” so make sure you test it properly on different screen sizes.

@derberg
Copy link
Member Author

derberg commented Mar 16, 2023

Nice!

neat idea with moving jobs to footer

@akshatnema you agree with proposal to have it as @M3lkior and @fmvilas suggest, between community and blog?

Copy link
Member Author

@derberg derberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@akshatnema ok, so jobs was already in footer, so now removed from top nav and case study added between community and blog. You ok with that?

@akshatnema
Copy link
Member

Yeah, I'm okay with the navbar. But just make sure that you update the Navbar in both Desktop and mobile view.

@derberg
Copy link
Member Author

derberg commented Mar 17, 2023

@akshatnema I updated it in one place and it is changed everywhere, mobile too. Just checked. Actually writing this command from mobile 😃

ready for final approval folks

M3lkior
M3lkior previously approved these changes Mar 17, 2023
akshatnema
akshatnema previously approved these changes Mar 17, 2023
Copy link
Member

@akshatnema akshatnema left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To my surprise ✨, @derberg made a good layout of a page with correct CSS 😄. So, this time, for further reviews, approving it ✔️

@quetzalliwrites
Copy link
Member

image

Currently, I see this problem to fix… The hyperlink text should not say read when the link directs you to a video.

This should be updated to say, watch our video or something along those lines

@derberg derberg dismissed stale reviews from akshatnema and M3lkior via 9ddd06b March 17, 2023 16:18
Copy link
Member Author

@derberg derberg left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@alequetzalli omg omg omg thanks for spotting it 🤣 it was actually a placeholder as when I created landing page, there was no readme yet. So I linked to Polish disco polo song (music that polish people complain is shit, but when there is a party we dance to it like there is no tomorrow 😆 )

anyway fixed to link to readme section that will be added with this PR

@derberg derberg requested review from M3lkior and akshatnema March 17, 2023 16:21
@quetzalliwrites
Copy link
Member

Good thing my autistic eyes miss NOTHING 😎🥸🤪

Copy link
Member

@quetzalliwrites quetzalliwrites left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚢🚢🚢🚢🚢🚢🚢🚢

@akshatnema
Copy link
Member

@derberg, over to @fmvilas as he need to approve it too to merge this PR 😄

Copy link
Member

@fmvilas fmvilas left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🚢 🇮🇹

@derberg
Copy link
Member Author

derberg commented Mar 20, 2023

😃 I'M SO DAMN HAPPY ABOUT THIS ONE 😃

/rtm

@asyncapi-bot asyncapi-bot merged commit 20a31a0 into asyncapi:master Mar 20, 2023
@derberg derberg deleted the casestudy branch March 20, 2023 12:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants