Improve how people see spec in the website

derberg commented 3 years ago

Reason/Context

Even though AsyncAPI specification markdown file is located in the spec repo, for a better UX we make it available in the AsyncAPI website too. We have proper automation in place that makes sure they are in perfect sync, so no worries 🍺

But we just render markdown as it is and that is it.

It is looooong markdown.

When you jump from 2.0 to 2.1 majority of the content is the same. How one can spot what changed?

Go to release notes? yeah, sure, why not. But you need to know where to look for, and anyway we can do much better here!

Description

Provide reference link to release notes. Somewhere on the top of every spec document we should also render link to GitHub release notes, where user also find link to more detailed article. So basically link from here -> here
Have some kind of toogle (supported as query param), that once enabled, provides a kind of overlay, a smarter view, where in the rendered document, parts that are new/changed are highlighted. I don't know yet how nicely present removed parts

AceTheCreator commented 3 years ago

@derberg wanna assign this to me?

derberg commented 3 years ago

@AceTheCreator only if you want it 😄

AceTheCreator commented 3 years ago

@derberg guess it's all mine now 😀

derberg commented 3 years ago

@AceTheCreator enjoy! 😄 first research, explore possible options, share with community progress and some screen shots on how you see it and then implement 😉

AceTheCreator commented 3 years ago

@derberg Thanks for the heads-up, I'll definitely follow your suggested approach

sambhavsaxena commented 3 years ago

@derberg How about using an accordion for summarized release notes of every version like so: https://react-bootstrap.netlify.app/components/accordion/#accordion

and a link to detailed release notes at the footer of this accordion?

derberg commented 3 years ago

@sambhavsaxena the problem is we do not have such "summarized" release notes, only full release notes

boyney123 commented 2 years ago

Just putting this here, not sure if it can help or not, but Codesandbox open-sourced a nice component that can help with docs.

https://codesandbox.io/post/sandpack-announcement

github-actions[bot] commented 2 years ago

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

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 :heart:

github-actions[bot] commented 2 years ago

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

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 :heart:

github-actions[bot] commented 1 year ago

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

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 :heart:

Harish-b-03 commented 1 year ago

Heyyyy @derberg , as discussed on slack, I am interested to take this task.

Do you have any ideas or suggestions to start with??

Thank you 😄.

derberg commented 1 year ago

I do not have too many ideas, or tools pointers for this one other than:

have much easier integration between spec doc and the release notes. In other words. When readers go to https://www.asyncapi.com/docs/reference/specification/v2.5.0 then should no be forced to figure out how to find release notes. Readers should see some "panel" or "note" that indicates the link to release notes. You know like "tl;dr if you want to quickly learn what is new, just grab release notes". This would have to be automated, not that someone manually adds it to specification document every time. Docs and release notes need to be "wired" in some way, maybe front-matter. Then during website build, if such "wire" is noticed then pannel is added to the website
- this is how release notes look like https://github.com/asyncapi/website/blob/master/pages/blog/release-notes-2.5.0.md
- this is how related spec documentation looks like https://github.com/asyncapi/website/blob/master/pages/docs/reference/specification/v2.5.0.md
Would be nice to have some kind of switch. Like dark/light mode one. A toggle that one can switch to say "show diff". So it highlights the UI parts of the spec document that were added to the document, modified, or deleted when compared to the previous version. You need to research tools that are good at figuring out text diff. I do not know of any good recommendations.

Both of the above ideas are good for people that follow spec from version to version. They use 2.4 and want to know what is in 2.5, and then they use 2.5 and in future they want to know what we added in 2.6, etc.

The thing is that there are also people that use 2.0 and want to figure if it makes sense to switch to 2.5. So we also need to figure:

how to also give them option to say "do not show default diff between latest and the last before, but lemme select what version I want to check against, maybe 2.1"
in the panned where we display release notes for 2.5 maybe we should also provide link like https://www.asyncapi.com/blog?tags=Release+Notes for all the other release notes? just for starter

Harish-b-03 commented 1 year ago

Heyy @derberg,

Have a look at this design

Note: Since the release note and specification document have same title, I used it to link the specification document with release note. For example, if an user visits 2.5.0 (post.title) documentation, we will be providing a link to release note like, https://github.com/asyncapi/website/blob/master/pages/blog/release-notes-${post.title}.md

I have also sent a message on slack regarding what I have done.

Thank you :smile:

derberg commented 1 year ago

lgtm, you just need to make sure https://github.com/asyncapi/website/blob/master/pages/blog/release-notes-${post.title}.md exists, as in case of release candidates there are no release notes, and we should not display this "box".

Technically I think the only place where you can check it is https://github.com/asyncapi/website/blob/master/scripts/build-post-list.js#L79. So if release notes exist, you add additional infor to details, like releaseNotesLink.

also, remember that final link to use there is https://www.asyncapi.com/blog/release-notes-2.5.0 (for example, so not link to GitHub but asyncapi.com)

derberg commented 1 year ago

in the panned where we display release notes for 2.5 maybe we should also provide link like https://www.asyncapi.com/blog?tags=Release+Notes for all the other release notes? just for starter

what about this?

Harish-b-03 commented 1 year ago

Heyy @derberg ,

Yeah, will consider these points. Will let you know about the progress, once I complete this stage.

Thank you

github-actions[bot] commented 1 year ago

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

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 :heart:

adarsh500 commented 1 year ago

Hey @derberg, I'd like to work on this. Since the main website is built with Next.js. We have some amazing tools like Contentlayer. This will help us populate the routes and the pages at build time. I've worked with this tool before and I'm using it for blogs on my website built with Next.js 13. I'd like to know your thoughts on this :)

derberg commented 1 year ago

@adarsh500 this tool looks interesting, but can you specify what it has to do with this issue?

more challenging is how to present in the UI the diff information.

@Harish-b-03 not sure if you work on it. Can you share all you learned so far?

Harish-b-03 commented 1 year ago

Heyy @derberg

As I mentioned on slack, I am not working on this issue.

Thank you 😃

derberg commented 1 year ago

oh, thanks, I must have missed that info, sorry

@adarsh500 I think Harish was giving a try to jsdiff

adarsh500 commented 1 year ago

Oops sorry, misunderstood the issue. I thought there issue was with rendering markdown files

sambhavgupta0705 commented 8 months ago

@adarsh500 what's the current status?? @derberg is this issue still relevant?

github-actions[bot] commented 3 months ago

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

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 :heart:

asyncapi / website

Improve how people see spec in the website #367

Reason/Context

Description