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

Re-build the JSON Schema Implementations page - (Design) #160

Closed
benjagm opened this issue Oct 18, 2023 · 24 comments
Closed

Re-build the JSON Schema Implementations page - (Design) #160

benjagm opened this issue Oct 18, 2023 · 24 comments
Assignees
Labels
✨ Enhancement Indicates that the issue suggests an improvement or new feature. 🎯 Roadmap This issue is intended to work on Roadmap items. Status: Do not close This is a long term issue with dependant issues. This label prevent it to be closed automatically.

Comments

@benjagm
Copy link
Collaborator

benjagm commented Oct 18, 2023

With the release of the new JSON Schema website, we still have plenty of range of improvement in the Implementations page. A new data-driven page, with filters and more call to actions to add implementations or try bowtie will improve the UX and the impact of this very important page.

Current page: https://json-schema.org/implementations

Inspirations:

Live Low-fi Prototype: https://docs.google.com/presentation/d/1cCjQO0tdUqf74iEtYYv7E2dHxYyZbbzL_sEQ1_64W1Y/edit?usp=sharing

Slack thread: https://json-schema.slack.com/archives/CT8QRGTK5/p1697620659557929

@benjagm benjagm added the ✨ Enhancement Indicates that the issue suggests an improvement or new feature. label Oct 18, 2023
@benjagm
Copy link
Collaborator Author

benjagm commented Oct 18, 2023

Feedback provided by @Relequestual on Slack:

  • For filters
    • When on Desktop, have them across the top, and sticky (stay when you scroll, and not on mobile)
    • For mobile, a filter button which opens an overlay with the filter options (like the main menu)

I don't want to take up more horizontal space. Some implementations have a lot of text, so the small width design might not work.

Should default to only showing draft-07 and above, but make it clear that a filter is enabled.

For categories, we should have some information that details what they mean. How and where we display that data can be discussed.

I know this is more of a technical detail, bot for many of the non-validation implementations, we do not know what drafts/versions are supported. We should have a filter for "unknown" or "undefined".

A link for adding an implementation is a good idea. Where we position that if we choose to put filters horizontally about the content, I'm not sure.

I think having a filter and maybe a column for Bowtie report ("Bowtie report (compliance)") would make sense. We would need to explain what that means.

For the "adding your tool", maybe we want "Something missing/wrong?" to include updates or changes and not just new tools.

Could do:

  • We may want to add a filter for licence which is "All OSI approved licences"
  • When selecting language/s, show number of results based on other filters (or grey out 0 result options)
  • Reset all filters button
  • Options in "drafts" to select all "modern" aka draft-07 and up, in one go

Aside: Do we want to say "drafts" or "versions"?
Under versions, we could say "draft-07" etc, but then "2019-09" and "2020-12" without "draft".
Great start! =]

@big-andy-coates
Copy link
Contributor

big-andy-coates commented Nov 16, 2023

Hi @benjagm,

What's the plan for the Benchmarks section on the existing implementations page?

I ask as I totally missed there were benchmarks when I was researching which JVM based validator implementation to use (and ended up writing my own).

I know we're moving towards Bowtie:heart: for functional comparison, but the performance comparison these benchmarks provide are also very useful.

Until Bowtie covers performance testing as well, it would be great if the new page could make the presence of these benchmarks more visible.

The new page is data-driven, so maybe there should be a section in the data for benchmarks, which can list the implementations they cover. Then use this to add a column to the table of validators with links to all benchmarks that cover a specific implementation.

The same pattern could be used to highlight any benchmarks the community has written for other sections, e.g. schema generators, etc.

An alternative would be to allow each implementation to list the benchmarks that are available for it. Though we should be careful to not allow implementations to remove unfavourable benchmarks without good cause.

Thoughts?

@benjagm
Copy link
Collaborator Author

benjagm commented Nov 16, 2023

Then use this to add a column to the table of validators with links to all benchmarks that cover a specific implementation.

I like a lot you proposal of a Benchmark column with Bowtie and the rest of benchmark tools like yours. I think we can do it and we'll have that in mind when designing the data model and when building the new page.

@Relequestual
Copy link
Member

Hey @big-andy-coates. I think I understand what you're asking here. You're asking that, for benchmarking solutions/tools, you'd like for there to be space in the data for listing what implementations have been benchmarked?

The space for columns is pretty limited. Very much open to ideas though.
There aren't many benchmarking solutions. Do you think it would be enough to just add "has benchmark" with a link to the benchmarking section appended to the "about" column data?

@big-andy-coates
Copy link
Contributor

Yes, that would work. Ideally, linking to the correct language section of the benchmarks

@big-andy-coates
Copy link
Contributor

Would be great if it could link to the benchmark section, with it pre-filtered to only the benchmarks that cover it.

Though, given the small number of benchmarks it might not be worth the effort

@benjagm
Copy link
Collaborator Author

benjagm commented Nov 28, 2023

Additional requirement captured in the last OCWM #536:

We'll add old implementations to the source datamodel of the new implementers page so we have everything in one single database and we can better tune the data shown in the implementers page.

@benjagm
Copy link
Collaborator Author

benjagm commented Jan 2, 2024

Adding here the last version of the designs

Mobile-Doc-Implementation- V2
Mobile-Doc-Implementation Side nav- V2
Desktop-Docs-V2

@benjagm
Copy link
Collaborator Author

benjagm commented Jan 2, 2024

Note than we have an open discussion about the behaviour of the Bowtie/Benchmark column, but we don't need another design for it.

@jdesrosiers
Copy link
Member

The old site had additional notes about compatibility that I'm now noticing aren't on the new site. For example, ajv included a note that you need to turn off strict mode to get spec compliant behavior. I think that's important information that needs to be expressed somehow on this page and there doesn't seem to be a place for that kind of information in the proposed design.

@Relequestual
Copy link
Member

Overall this looks better than what we have currently.

I don't think we need a "subscribe to our newsletter" banner half way through.

I am not sure about the filters being on the left on the deskop. What I said in my previous comment still stands and I prefer the other design. Open to other's thoughts.

For the desktop version, I do not think it best to hide away details and require a mouse over/hover to see details/comments. These should be visible and obvious.
For mobile, I know space is limited, but there is also no mouse hover.

In relation to the "add your tool" call to action, I think this might be better as an "Edit on GitHub" CTA, which takes people to a readme whcih explains they can either make a PR or raise an Issue for someone else to add/modify the data.

When a filter is active, the number of implementations should change, and show something like "100 implementations (of 258)".

On mobile, we should show the active filters when the filter selection menu is closed.

I realise most of these are functional requirements rather than design, but we may ask for some elements to be designed. Or we can just capture the requirements (if we agree) as a task list to check off in this Issue when reviewing the PR.

@benjagm
Copy link
Collaborator Author

benjagm commented Jan 10, 2024

The old site had additional notes about compatibility that I'm now noticing aren't on the new site.

Thanks a lot for finding this bug. I created this issue #270 and I am working on it.

@benjagm
Copy link
Collaborator Author

benjagm commented Jan 11, 2024

The old site had additional notes about compatibility that I'm now noticing aren't on the new site.

@jdesrosiers this is fixed with this PR: #271

@benjagm benjagm moved this from In Progress to Waiting for Contributions in Website Contributor Board Jan 19, 2024
@benjagm
Copy link
Collaborator Author

benjagm commented Jan 19, 2024

Another requirement for the page is the availability to properly track with UTMs how JSON Schema users are accessing the implementations so we can identify trends and insights.

@benjagm benjagm moved this from Waiting for Contributions to Todo in Website Contributor Board Feb 13, 2024
@benjagm benjagm added the Status: Available No one has claimed responsibility for resolving this issue. label Feb 20, 2024
@aialok
Copy link
Member

aialok commented Feb 20, 2024

@benjagm , I would love to work on this issue : )

@Sanket-0510
Copy link
Contributor

@benjagm I would like to give it a try!

@benjagm
Copy link
Collaborator Author

benjagm commented Feb 22, 2024

Thanks everyone for your interest!

Please get yourself familiar with the project by completing one the the good first issues available in this board: https://github.com/orgs/json-schema-org/projects/16

@Michael-Obele
Copy link
Contributor

Feature request: Dark theme option

I'd like to propose adding a dark theme option to the website. I believe it would improve the user experience by offering a more comfortable viewing option in low-light environments and for users (like me) who prefer dark themes.

@Michael-Obele
Copy link
Contributor

Feature request: Dark theme option

I'd like to propose adding a dark theme option to the website. I believe it would improve the user experience by offering a more comfortable viewing option in low-light environments and for users (like me) who prefer dark themes.

My bad, seems like this is an already-open issue (#130)

@AdityaSingh-02
Copy link
Contributor

Hello @benjagm

Hello! I'm Aditya Singh, a Computer Science undergraduate from India with a passion for open-source contributions. Previously, I had the opportunity to participate in Google Summer of Code 2023 at Rocket.chat, which was an enriching experience. This season, I'm eager to channel my skills and knowledge into contributing to JSON Schema. The project's requirement matches my tech stack, and I'm excited about the potential impact I can make by contributing to JSON Schema. I'm looking forward to making some worthy contributions🚀

x - https://twitter.com/Go_D_Aditya

@AdityaSingh-02
Copy link
Contributor

For Developing a new version of JSON schema Implementations page -

  • The main focus of this project would be to improve overall user experience for the implementations page.

  • I would focus on building new version for both mobile as well as desktop keeping the page responsive.

  • I would create a filter that would-

    • When on Desktop, have them across the top, and sticky (stay when you scroll, and not on mobile)
    • For mobile, a filter button which opens an overlay with the filter options (like the main menu)
  • This project would mainly include of creating new components and replace the existing components with the newer one’s…

  • Further discussing, I have gone through the designs for both desktop and mobile view, This project uses NextJS and tailwind CSS for the frontend styling and I have hands on prcatice with it.

@benjagm benjagm added Status: Blocked There is another issue that needs to be resolved first. and removed Status: Available No one has claimed responsibility for resolving this issue. labels Mar 4, 2024
@VivekJaiswal18
Copy link
Contributor

VivekJaiswal18 commented Mar 6, 2024

Hey @benjagm, since it has no assignees can I be assigned this issue. I would love to contribute to this issue

@lowkya
Copy link

lowkya commented Mar 30, 2024

Hey @benjagm

The mockups are good. I like the features such as adding filters and ordering the options in the filter alphabetically, as well as adding descriptions on hover, etc.

However, I do have a few suggestions that I believe would enhance the overall user experience:

  1. There appears to be some misalignment between the table headers and the table values. Aligning these properly would improve the user's view.
  2. Currently, all the data is bold, which I think imposes too much cognitive load on the user. Selectively using bold text for emphasis rather than bolding everything would be more effective.
  3. The languages are repeated excessively in the table content. For instance, in the 'Validators' table, 'C++' is mentioned as both a column header and a value in the subsequent three lines. This repetition seems unnecessary and could be streamlined by removing one instance.
  4. The use of bold for 'Bowtie' in the text for 'Try Bowtie' seems unnecessary and could be omitted.
  5. It would be beneficial to have a designated area to display selected filters and provide users with the option to remove filters from there. This feature would enhance usability.
  6. If applying filters results in an empty table, it would be helpful to display a message such as 'No results found' within the table's content. This aspect was not entirely clear from the mockups.

@benjagm benjagm added the 🎯 Roadmap This issue is intended to work on Roadmap items. label Apr 5, 2024
@benjagm benjagm moved this from Todo to In Progress in Community and DevRel Plan Apr 5, 2024
@benjagm benjagm changed the title Re-build the JSON Schema Implementations page Re-build the JSON Schema Implementations page - (Design) May 28, 2024
@benjagm benjagm added Status: Do not close This is a long term issue with dependant issues. This label prevent it to be closed automatically. and removed Status: Blocked There is another issue that needs to be resolved first. labels Jun 10, 2024
@benjagm
Copy link
Collaborator Author

benjagm commented Jun 10, 2024

Let's continue the discussion in #716

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
✨ Enhancement Indicates that the issue suggests an improvement or new feature. 🎯 Roadmap This issue is intended to work on Roadmap items. Status: Do not close This is a long term issue with dependant issues. This label prevent it to be closed automatically.
Projects
No open projects
Status: Done
Development

No branches or pull requests