Create New page for /tools/ #383

Closed iamVP7 closed 1 year ago

Latest description for the issue -> - list can still be enhanced manually as some tools are not on GitHub, there are some on GitLab

Reason/Context

Why we need this improvement? Creating new index page for tools page.
How will this change help? We can say what each and every tool does.
What is the motivation? We are moving pages related to tools under /tools/* so a dedicated index page for tools alone

Description

What changes have to be introduced? A new page.
Will this be a breaking change? New page; mostly changes are restricted to new page. If broken it wll be mostly this page.
How could it be implemented/designed?

@iamVP7 can you provide the mockup for the page. I would love to work on this

Raised this feature request during code refactor (#378 )

I feel @derberg will be good person to share the thoughts on designing new page.

I would ask our design contributor extraordinaire, @mcturco for design contributions. 😀👍🏽

Lukasz is awesome, but not in design 😄🙊

but not in design 😄🙊

I could not agree more 🤣

I'm not sure we are at the stage where we can start working on it. @alequetzalli isn't it somehow connected also with new docs page? I mean there will be docs restructuring, and we also want to incorporate docs from tools, and we also want to clean up that some tools are in one location and some are now described in the documentation. A lot of factors that can influence design, @mcturco will ask questions I personally do not have a clear answer to yet. This might be a good candidate for GSoC related task, as it requires discussions with community, and driving it end to end. Don't know 🤷🏼

@derberg I was about to say the same thing. Before we can start developing a new page we definitely should discuss what the purpose is if different from the tooling docs and what content we would need to present. Once we have a clear direction and content written, we can begin designing a layout for this (again, if it will be different than the docs)

I'm not sure we are at the stage where we can start working on it. @alequetzalli isn't it somehow connected also with new docs page?

I don't think so? I think I see the Docs as a different item than what I understood @iamVP7 was asking to do in this issue. I understand this issue to mean he wanted to know if we could add a page to our website to mention Tools. I guess I thought he opened this issue to ask if we could consolidate all our diverse tool landing pages into a single one. We currently have several individual pages or links to see the tools, but not a single one in the website just briefly summarizing each one. Thus, I thought it would be a question for say, @derberg, @mcturco, or maybe @magicmatatjahu to start a discussion w/ community on the why for this page.

That said, if I misunderstood his question, and he was instead asking about having the Tools documented, then yes.... this would be a question for Docs.

@iamVP7, can you confirm to us if you were wanting to document the Tools (for AsyncAPI Dev Docs), or if you were asking about making a landing page in our website for all the Tools?

As per @derberg comment, we were in need of landing page for tools.

Even I felt, it might be helpful to have landing page (say something like feature page for random project), as it can help with SEO.

Got it, he may have forgotten that is what you were referring to! Thank you for clarifying @iamVP7.

So if you're proposing a landing page, which is not related to Docs, then I will let @derberg and @mcturco take over this with you. You'll prob work with them to propose your solution to the community and see what the community thinks this page would need. 😀👍🏽

Great thank you both for the clarification @alequetzalli @iamVP7 I am understanding the idea now 😄

I think this is a great idea! It definitely will help to have that main /tools slug not reach a 404 😅 good catch! We will first have to start thinking about what kind of content we would need to include on this new page. Are there any other sites that we can use for inspiration? I think generally we can use this new page to showcase and link out to each tool, but just thinking about what else we can include on that page.

Screen Shot 2022-02-01 at 6 10 34 PM

@mcturco What if it had cards in a grid, and each card represented a tool?

@alequetzalli yeah I think that's a great idea! Let's do it!

This issue is about having a single landing page that lists all the tools for AsyncAPI, not only the ones that are maintained by AsyncAPI:

We have tools:

here https://www.asyncapi.com/docs/community/tooling
here under Tools button/dropdown

We still need pages like:

https://www.asyncapi.com/tools/cli
or pages with full documentation, like we plan for generator for example

We should have one single landing page under https://www.asyncapi.com/tools where:

we have a list of all the tools for AsyncAPI
we have nice filtering and not hard to navigate tables like https://www.asyncapi.com/docs/community/tooling
we can still have a category that given tool is maintained by AsyncAPI, so I can filter out only tools from AsyncAPI initiative
filters should be enabled on URL level, so I can have for example a link like https://www.asyncapi.com/tools?asyncapi to get a list of tools that are owned by AsyncAPI Initiative
I should be able to filter out tools by languages (JS, Java), area (CI&CD, testing) or type (library, cli, web)

Key - discoverability:

now I can add a tool by opening a PR to the website repo but it requires extra effort that could be automated. Manual == boring and pushing away
list should not be a markdown file like now but json or yaml file that is built by some GH workflow
list is build based on GitHub search. Take this example. Arjun should just be required to only add certain topics to the repository, maintain accurate description, and that is it. We will automatically pull the tool to the list
list can still be enhanced manually as some tools are not on GitHub, there are some on GitLab
we should have some alerts when a new tool gets discovered? Slack channel alert? a maybe automated Tweet?

For now I think about simple repo description and topics, might be that long term better to introduce .asyncapi file that Arjun would need to maintain in his repo and all metadata for the tooling list would be provided there in the file.

For GSoC participants

This issue is interesting for GSoC because:

you get to do some frontend work,
JS coding and GitHub API usage is included
You get to learn basics of GitHub Actions
you will need to have discussions with different folks from AsyncAPI that will show you the real job work when in theory simple solution requires discussion with multiple folks in a company. The difference is that in open source it is even more complicated :smiley:

@derberg Hmm :thinking: this idea looks fascinating and interesting to me. I am designing the solution in my plan(for gsoc) and looking to make a proposal on it. But, I want more information regarding this idea. As discussed by you on Slack, you proposed me this:

To make a .asyncapi file from which data is extracted using GitHub API and is updated manually by organization members. So, where should we place this file? in website repo or .github repo so that it can be accessed to every repository and can be fetched easily from other repos?

Also, later we will have a prebuilt json file built using scripts but will be under .gitignore because the file will be built during build time and then rendered on the website (Same what we do in posts.json). This file will be updated using GH workflows on the production side. This is the overall plan you give me and I thought of. Also, I am actively looking for some more suggestions on this approach from everyone :smile:. We can have other approaches too for the listing of data. If you have anything more to correct me or suggest me, do tell me. It will be my pleasure to discuss with you.

Regarding filtering of tools in the list and design of the page, it is pretty much straightforward that whenever a user will filter out some tools, those filters will be updated on URLs as well as query params to search in the list. We can have a customized search bar at top of list, where categories are mentioned in a dropdown for users to search. New page (or route) /tools/ will be made easily in the repo and it can be further extended in the future to add more information related to it.

Hey @derberg, I am willing to continue to work on this issue in Mentorship program. Kindly look on my previous comment and do give your suggestions on how I should improve it.

@akshatnema Hi!

To make a .asyncapi file from which data is extracted using GitHub API and is updated manually by organization members. So, where should we place this file? in website repo or .github repo so that it can be accessed to every repository and can be fetched easily from other repos?

As I understand that file should be located on the tool's repository side and then in website workflow we should filter all repos with that file and make appropriate logic. Let me know if you understand. Also I prefer .asyncapi-tool or .asyncapi-webiste due to simple fact - we can introduce .asyncapi config file in our CLI, so it's better to have a different name.

Also, later we will have a prebuilt json file built using scripts but will be under .gitignore because the file will be built during build time and then rendered on the website (Same what we do in posts.json). This file will be updated using GH workflows on the production side. This is the overall plan you give me and I thought of. Also, I am actively looking for some more suggestions on this approach from everyone 😄. We can have other approaches too for the listing of data. If you have anything more to correct me or suggest me, do tell me. It will be my pleasure to discuss with you.

We'd have to hear from Łukasz here, but from what I understand it's a good approach. However, as Łukasz mentioned you need to figure out a way to retrieve this data from the repositories via Github API, this will probably be the hardest part here.

Regarding filtering of tools in the list and design of the page, it is pretty much straightforward that whenever a user will filter out some tools, those filters will be updated on URLs as well as query params to search in the list. We can have a customized search bar at top of list, where categories are mentioned in a dropdown for users to search. New page (or route) /tools/ will be made easily in the repo and it can be further extended in the future to add more information related to it.

👌🏼 great.

you need to figure out a way to retrieve this data from the repositories via Github API, this will probably be the hardest part here.

@magicmatatjahu Yep, it is pretty much difficult to filter out the repos of the specific tools, but what I think is that if we assign specific tags to the repositories having tools, we can make a json fiile according to it. But the condition is, we need to specify tag, category or topics on the repo and each repo should contain exactly one tool in it. Using GitHub GraphQL API, we can extract the tags attached to each repository and store there information in the prebuilt.json file. The .asyncapi-tool file will contain the name of the topics, and categories that will be used to filter out the tools from the repositories. Additionally, some manual tools can also be added to asyncapi-tool file, which will be later added to the prebuilt.json file during build time.

What I didn't get is the GitHub search that Lukasz mentioned in his previous comment. Some Github search implementation has been made in the cupid repository by Arjun, but I wasn't able to find in it. If you know, kindly send me the reference link of that particular function in the codebase.

@akshatnema

The .asyncapi-tool file will contain the name of the topics, and categories that will be used to filter out the tools from the repositories.

Yep, but it should contain also another info like description, title, maintainer etc. Of course we can also extract that info package.json, but we should discuss it.

What I didn't get is the GitHub search that Lukasz mentioned in his previous comment. Some Github search implementation has been made in the cupid repository by Arjun, but I wasn't able to find in it. If you know, kindly send me the reference link of that particular function in the codebase.

Łukasz specified cupid as repo for searching - given repo will have topics and .asyncapi-tool file and based on that we will filter repos :) It's only an example for your task.

@akshatnema I love how far detailed you went with the research. The final solution is not written in stone, like file names and stuff like that. The only strong requirement:

not PR based but discovery based
enable an easy way to add support to other platforms for discovery, like GitLab (I know about at least one AsyncAPI tool that is hosted there, docs generator for Asciidoc)

I'm not sure if topics is a better solution over .asyncapi file. IMHO best to propose 2 alternative solutions and show to some tooling owners (that will be users of this solution) to say what is the best for them. For sure .asyncapi is easier to extend in future with more metadata, more than you can get with topics

Super happy to see you engaged here so much. Will advertise it among TSC to make sure it is selected as it is going to be a great addition for the community IMHO

Hey @derberg, I understood your previous comment and thus, came up with another approach to target this. Do give your views on it. Here it is as follows:

First part of the approach - We will be using Web scraping here on the JSON data provided by GitHub and GitLab APIs because we can only rely on these APIs since most of the tools are present here only (Do tell me if we have a centralized place/file to collect metadata of all tools we want to target in this issue). Using GraphQL APIs, we will get the description and other required information of all the repositories in AsyncAPI. This data(in JSON) will not be stored permanently but will be used for scraping purpose.
Second part of the approach - The .asyncapi-tool file will contain the necessary tooling words which will be used to identify the required repositories containing the tools of AsyncAPI. The words or the keywords in the file will be manually added using the PRs and can be changed in future to more customize our scraping process as well as categorizing the various tools in different sections/topics. The file will also contain the other necessary information like the category names in which the tools are to be categorized on the website and the schema of the details needed for each tool that will be required while rendering it on website. In short, this file contains all the metadata related to the scraping process and the tools.
Third part of the approach - The description (if needed, the topics) of all repositories containing the tool will be updated in such a way that they describe the tool as well as they get identified the scraper function to add its details (acquired from the API) in the tools.json (which will be built on the build time). The text in the description will be scanned on the given keywords in the .asyncapi-tool file and hence will be added in tools.json. This file is then used to render data in the respective components in the website.

Key points to consider

Since, we are using web scraping, it's not going to be a fast process. Scanning around 60+ repositories in the JSON will take some time but since we are using JS, it will not affect the build time. (:thinking: Maybe it will take less time than build time of posts.json).
This approach will not make some weird additions on the repository. As mentioned by you earlier, we won't be adding too many topics in the repository to identify the tool. We are using the Description of each repo for the identification and categorization.
The description of each repository needs to be precise so that the scraper won't identify a non-tooling repository as a tool and add it in the tools,json.\
I made the approach mentioned above keeping in mind that all the tools are present either in GitHub or GitLab. If it is not so, do tell me about the other sources. OR do we have any centralized file/place which keeps account of every tool used in AsyncAPI.
An alternative for the description can be to use a certain prescribed file in the repositories that describes a tool and the file contains all the necessary topics/tags needed to identify and categorize it.

Waiting for an awesome reply from Lukasz (@derberg). I will be happier if @magicmatatjahu reviews this one as it deals with some code and algorithms as well :slightly_smiling_face:.

I think you guys like to make life difficult for yourselves. When I read about the .asyncapi-tool approach I immediately had in mind situations where we use this file on the repository side to describe the tool (its metadata), and you describe about scraping data and identifying by description etc...

(Maybe you have the same thing in mind as me, but reading your previous comments I'm confused and don't know if I understood your suggestions correctly)

My suggestion:

the owner of a given repository adds a topic (tag) to his/her repository asyncapi-tool.
he/she creates an .asyncapi-tool file where provides information about the project/tool like description, title, maintainers, href, docs (documentation link), category (of tool, like template, parser etc), maybe also website etc.
on building the website we download all the repositories from github using the asyncapi-tool topic, download the contents of the .asyncapi-tool file and we have all the metadata - for other sources like gitlab we should check if there is possibility for similar solution.

If someone provides additional topics he/she will be able to do that, but the most important thing is that there should be asyncapi-tool.

Definitely let us not consider web scrapping as a possible solution. GitHub search allows you to search for specific file in repos and as result, you get a list of repos. Then, afaik API allows you to just grab the content of the specific file, without cloning (something to confirm)

tl;dr

we do not need topics at all
all info for list of tools should be in .asyncapi-tool file
just take advantage of GitHub API

Yep, we can extract the file contents but not directly through the Github search. What you mentioned in your message are the features used to find files/repos using the Github search bar but we need want it using Github API. I found this in the Github REST API. I think using the above-mentioned API, we can find the file present in the respective repo but need to access the content which is quite hard as the API is not returning the contents of the file directly. We need to discuss regarding this on how to extract the contents of the file using the present JSON. For finding the AsyncAPI repositories using API, we can use this GET request of GitHub API.

As mentioned by you, if we only need to add .asyncapi-tool file in each tool repository and can extract data from it, then it is quite an easy and straightforward implementation that can be implemented inside scripts/ folder. We only need a addition of .asyncapi-tool file added to each tool and if it is not possible, the tools will be manually added to the /tools/ in the website. Do you need to add anything more in this that I missed and is important?

you have some example of search in action here: https://github.com/derberg/npm-dependency-manager-for-your-github-org/blob/main/lib/api-calls.js
search returns 2 props, repository with typical repository object where you can grab org/profile and repo name + path where found file is actually located in repo, root? maybe .github?
then you call for example https://api.github.com/repos/asyncapi/website/contents/README.md
decode content string with base64

and enjoy life 🍹 🏖️

the only thing now is I think to agree on the structure of the .asyncapi-tool file

then you call for example api.github.com/repos/asyncapi/website/contents/README.md decode content string with base64

As what I see in the API docs and its schema, we get a url variable containing the link of the contents inside the file (in base64 encoded form). The schema of the url is as follows:

 "url": {
            "type": "string",
            "format": "uri"
          },

We can call the GET request on this url to get the contents and then convert them into the normal text then. Do confirm if you want to convey this only?

the only thing now is I think to agree on the structure of the .asyncapi-tool file

I will try to make one draft schema in the upcoming days but in the format of a javascript object (that's my most preferable way :sweat_smile:). If you want it in another format, do tell your suggestions.

We can call the GET request on this url to get the contents and then convert them into the normal text then. Do confirm if you want to convey this only?

sounds good to me

I will try to make one draft schema in the upcoming days but in the format of a javascript object (that's my most preferable way 😅). If you want it in another format, do tell your suggestions.

yeah, leave out schema for now, first focus on example JSON objects. Let us agree on the structure, and then to get schema out of it later is easy. Definitely do not start with schema first

Hey @derberg @magicmatatjahu can you please tell me some categories for the tools on which we can filter the tools?

I'm trying to make a JSON object for the .asyncapi-tool file.

I made a template JSON object for .asyncapi-tool but I think it still needs some more fields to be added. Do give your suggestions regarding the JSON object and schema.


{ 
    "title": "",
    "description": "",
    "maintainers": ["", ""],
    "links":{
        "url": "", // Website url of the tool. Ex: http://asyncapi/tools/cli
        "docs_url": "", // Documentation url of the tool.
        "repo_url": "" // Repository url of the tool
    },
    "category": {
        "languages": [""], // Like NodeJS, React JS
        "area": [""], //  Like CI/CD, testing
        "type": [""], // cli, parser, web, library
        "isAsyncAPIowner": true //boolean
    } 
}

@akshatnema Nice! 🚀 My insights:

I think that we should have shape for single maintainer like:

{
"name" : "Barney Rubble",
"email" : "b@rubble.com",
"url" : "http://barnyrubble.tumblr.com/"
}

about links.repo_url. If we will fetch data from Github API we will have url for repo, yes? So I don't think so that we need it.
category. isAsyncAPIowner I don't think so that we need it, because we can check on the fetching side that given repo is under asyncapi organisation.
maybe we should also add technology next to category.languages? For example, ReactJS is technology (library) not language.

The rest is good for me. @derberg What do you think?

I think that we should have shape for single maintainer like:

Fine, I'll update this change.

about links.repo_url. If we will fetch data from Github API we will have url for repo, yes? So I don't think so that we need it.

Yeah, it will not be needed in the .asyncapi-tool file but will surely be added in the tools.json file when compiling all the tools.

category. isAsyncAPIowner I don't think so that we need it, because we can check on the fetching side that given repo is under asyncapi organisation.

Hmm, it will be helpful if this field is added, because there will be need to add manually this field in the JSON object in the script.

maybe we should also add technology next to category.languages? For example, ReactJS is technology (library) not language.

Yeah, definitely :+1:

@akshatnema this idea was selected for AsyncAPI Mentorship 2022 -> https://github.com/asyncapi/community/discussions/376#discussioncomment-2890658

I love how much you are engaged with the work on AsyncAPI website and how active you are, especially in this issue. Would you like to be an official AsyncAPI-sponsored mentee for this issue?

I love how much you are engaged with the work on AsyncAPI website and how active you are, especially in this issue. Would you like to be an official AsyncAPI-sponsored mentee for this issue?

Thanks @derberg for selecting me. I will love to work under your mentorship and look forward to the mentees' onboarding. And yes, I will like to become an official AsyncAPI-sponsored mentee for this issue.

@akshatnema added you to the list 🥳

Hmm, it will be helpful if this field is added, because there will be need to add manually this field in the JSON object in the script.

you will be able to determine it on the client side, I mean determine if it is tool from AsyncAPI org or not

@akshatnema can you share an updated .asyncapi-tool structure basing on the feedback you received?

I also suggest we should have a prop like fileVersion where we can specify what version of the .asyncapi-tool schema is followed, so it is much easier to handle it on our side in the website. In future this file may evolve, and structure change, so we better handle it this way

I think we should also discuss on the extra markdown file we will have to add extra tools? Regarding the structure of the table and how we will convert that data to JSON.

This is the updated .asyncapi-tool structure I made till now, based on your reviews. Anything more you want to add?

{ 
    "title": "",
    "description": "",
        "fileVersion": "",
    "maintainers": [
        {
            "name" : "Barney Rubble",
            "email" : "b@rubble.com",
            "url" : "http://barnyrubble.tumblr.com/"
        },
    ],
    "links":{
        "url": "", // Website url of the tool. Ex: http://asyncapi/tools/cli
        "docs_url": "", // Documentation url of the tool.
    },
    "category": {
        "languages": [""], // Like JS, TS
    "technology": [""], // Like NodeJS, React JS 
        "area": [""], //  Like CI/CD, testing
        "type": [""], // cli, parser, web, library
    } 
}

Hi! @akshatnema reached out to me to give my guidance on implementing a UI design for this new page. I would say that before we can start designing anything, we should have a breakdown of all the content/elements that we want to have on this page so we know what kinds of UI elements we will need. This breakdown can just be a list in a comment on this issue.

Do you want to tackle that first, @akshatnema?

I think we should also discuss on the extra markdown file we will have to add extra tools? Regarding the structure of the table and how we will convert that data to JSON.

no need to keep it in markdown, just need to grab the current markdown, and manually transform it into JSON, and then on CI level, merge "manual" JSON with the generated one (excluding duplicates)

This is the updated .asyncapi-tool structure I made till now, based on your reviews. Anything more you want to add?

@magicmatatjahu what is your view on fileVersion?

we need to determine what props are required and what not
maybe we should do YAML?
I suggest area to be category and we should say what list of categories are allowed
what is the idea behind the type?

Hi! @akshatnema reached out to me to give my guidance on implementing a UI design for this new page. I would say that before we can start designing anything, we should have a breakdown of all the content/elements that we want to have on this page so we know what kinds of UI elements we will need. This breakdown can just be a list in a comment on this issue.

Yes we need a clear outline for you really because in UI we will show more than just what is in .asyncapi-tool

Some inspiration -> https://openapi.tools/

no need to keep it in markdown, just need to grab the current markdown, and manually transform it into JSON, and then on CI level, merge "manual" JSON with the generated one (excluding duplicates)

This looks like the toughest job in this idea :sweat_smile: because we need to first grab the correct part of markdown to convert into JSON, and then make a type of comparison algorithm/code to exclude the duplicates and append the extra tools in JSON as well. Thanks for reminding me, I must keep this in my account (my Notion) to not forget about it.

Do you want to tackle that first, @akshatnema?

@mcturco Yeah, I will soon drop here the major outlook and key elements in the UI to further make the correct designs according to the need.

@derberg @akshatnema

@magicmatatjahu what is your view on fileVersion?

As I understand, fileVersion is something like asyncapi field in spec to determine which version of .asyncapi-tool we are using? If yes, I like it. When we will change the structure of given file, then we will know which version we handle.

@magicmatatjahu exactly, and I had no better name to propose, I just new version would be confusing as people would think it is a tool related version

Hey @mcturco, I have made a rough sketch of the Tools dashboard. I think it will be good to you to make a Figma design according to it. Please don't consider it as a strict outline to follow it. You can surely add your creative and new components there to implement it in a better way. Do tell me if you want to add something more to it. Here's the link: https://miro.com/app/board/uXjVOpY2xGc=/?share_link_id=116049100995

Preview of my imagination :sweat_smile:

Hey @akshatnema!

Thank you so much for providing this wireframe sketch, I can definitely see your vision: no fancy UI needed/necessary and that will always be one of the last steps in the process anyways 😄

My thoughts: I love the cards to represent each tool and I think having them in a 2-col layout would look nice and be easy to digest. However, I am questioning if we really need all of those categories... I think this could cause great confusion in the UX and can definitely be over-complicated as you are trying to use the filters. We have to ask ourselves... when someone is looking for free open source tooling, what are they going to look for in it at first glance? I would say that we should limit it to 1-2 categories, at least for this UI implementation. I would assume that the first thing the user is looking for is what code language it is written in, and if we really felt like we had to add another category, maybe a category of tooling (ex: CLI, UI, etc) Would love to know what you and others think! But we are definitely on the right track here 💪

@mcturco See at the end, we do need all the categories to be used as filters. So, I will need 5 filters at the top and a clear filter button (that I forgot to make in my sketch :sweat_smile:). And if you are planning to not show all categories, a user may get confused after selecting a particular category. But yeah, if we only 2 categories, the tool card will be in rectangular shape and will be more better in terms of UI. So, we can go in this plan right now, but will look over to the reviews after the implementation.

So, I will need 5 filters at the top and a clear filter button (that I forgot to make in my sketch 😅). And if you are planning to not show all categories, a user may get confused after selecting a particular category.

I don't even think that 5 different filters are necessary at this point. We could start with the 2 categories and a filter for each of those IMO. If you give the user too many options, they might get overwhelmed and quit the experience. I don't think we have that many official AsyncAPI tools right now for 5 filters to be useful tbh.

I don't even think that 5 different filters are necessary at this point. We could start with the 2 categories and a filter for each of those IMO. If you give the user too many options, they might get overwhelmed and quit the experience.

But there is also the point that I need to make those filters at some time in future. If you see the .asyncapi-tool schema, we have added those fields there to categorize/filter the tools according to them. If we are not adding the filters according to them, there's no point to add such fields and get the data of tools related to them. What's the key of the project is to make the tools easily categorized in terms of various fields. Do you have any option to convert the same functionality of 5 filters into 2?

@akshatnema maybe it will help if you provide @mcturco with real data? I mean, take existing markdown with list of tools and transform it into a JSON file that we will build based on input from users or .asyncapi-tool. This way we have really data that will help @mcturco understand our needs + we validate what categories we really want to have there, and which make sense. Win win 🤷🏼

@derberg @mcturco Here is my sample JSON data that will be used to render information related to tool and filter it out according to the category. @derberg Will you please check if the details of the tool are perfect?

{
    "title":"AsyncAPI Generator",
    "description": "Use your AsyncAPI definition to generate literally anything. Markdown documentation, Node.js code, Java code, HTML documentation, anything!",
    "fileVersion": "0.0.1",
    "maintainers":[
        {
            "name": "Fran Méndez",
            "email":"fmvilas@gmail.com",
            "image_url":"https://github.com/fmvilas.png"
        },
        {
            "name": "Lukasz Gornicki",
            "email": "lpgornicki@gmail.com",
            "image_url":"https://github.com/derberg.png"
        }
    ],
    "links":{
        "url": "",
        "docs_url": "https://github.com/asyncapi/generator/tree/master/docs",
        "repo_url": "https://github.com/asyncapi/generator"
    },
    "category": {
        "languages": ["Javascript", "HTML", "Java", "Python", "Typescript"],
        "technology": ["Nodejs", "Spring", "Paho", ".NET"],
        "area": ["template"],
        "type": ["cli", "generator"],
        "isAsyncAPIOwner": true
    }
}

Small correction isAsyncAPIowner -> isAsyncAPIOwner :)

isAsyncAPIOwner should be at the root
fileVersion can be 1.0.0
url ?
also regarding the whole category object I asked few questions about it in the past 👇🏼
- I suggest area to be category and we should say what list of categories are allowed
- what is the idea behind the type?

Can you also show how would it look like in .asyncapi-tool? I guess in case of maintainers list we just ask for github handle, right?

fileVersion can be 1.0.0

I think it's under development phase right now, not in a stable release yet :laughing:

url ?

I changed it to image_url because we don't need here there GitHub handle. This is because we are already taking the email IDs which will allow them to directly contact the maintainers of the tool via mail. Since Github doesn't allow us to communicate with the users in personal chats, I think it's better to use their official mails then. OR do you want that instead of mails, we should only focus on taking github username and redirect the user to the github profile when clicked?

also regarding the whole category object I asked few questions about it in the past 👇🏼

I already added the area under the category and it is targeting the part of the job for which the tool being used, like CI/CD, testing, etc. type define the type of the tool, like whether it is a cli, webtool, parser, library, etc. Regarding the list of tags added inside these fields, it's better you and @magicmatatjahu discuss on these.

Can you also show how would it look like in .asyncapi-tool?

Right now, for the above JSON, .asyncapi-tool file looks like this:

{
    "title":"AsyncAPI Generator",
    "description": "Use your AsyncAPI definition to generate literally anything. Markdown documentation, Node.js code, Java code, HTML documentation, anything!",
    "fileVersion": "1.0.0",
    "maintainers":[
        {
            "name": "Fran Méndez",
            "email":"fmvilas@gmail.com",
            "image_url":"https://github.com/fmvilas.png"
        },
        {
            "name": "Lukasz Gornicki",
            "email": "lpgornicki@gmail.com",
            "image_url":"https://github.com/derberg.png"
        }
    ],
    "links":{
        "url": "",
        "docs_url": "https://github.com/asyncapi/generator/tree/master/docs",
    },
    "category": {
        "languages": ["Javascript", "HTML", "Java", "Python", "Typescript"],
        "technology": ["Nodejs", "Spring", "Paho", ".NET"],
        "area": ["template"],
        "type": ["cli", "generator"],
    }
}

I guess my concern is just that the 5 filters seem excessive, where I feel that a user can easily find what they are looking for in just 2 filters. To me, the area filter doesn't really give that much explanation of what the tool is, and type seems like it could be something similar to that?

It could just be that I don't have enough background knowledge to understand what is useful and what isn't when searching for tooling. What do others think about the current categories? Do we need all of them?

asyncapi / website