Skip to content

Update README.md to be clearer. #404

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

Open
wants to merge 1 commit into
base: develop
Choose a base branch
from

Conversation

alilleybrinker
Copy link

@alilleybrinker alilleybrinker commented Apr 25, 2025

View the rendered README.md here


This amends the README.md file to be clearer to navigate. This is achieved in several ways:

  • All links are now hyperlinks on explanatory text, instead of bare URLs.
  • Where appropriate, information has been gathered into tables.
  • How to participate in the QWG and contribute in the repository has been spelled out explicitly.
  • The distinction between the "production" and "development" versions of the format have been clearer by being split into distinct sections.

Copy link

@Rucellmai61 Rucellmai61 left a comment

Choose a reason for hiding this comment

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

#rucellmai61

@ccoffin ccoffin dismissed Rucellmai61’s stale review April 28, 2025 16:49

This review is not justified unless more details can be provided

@ElectricNroff
Copy link

My experience is that this approach to using tables for navigation would fail an accessibility review. The new design is an improvement for many users but doesn't interact well with some common assistive technology.

For example, when a screen reader is being used, and the user navigates through this:

| Format         | Link          |
|:---------------|:--------------|
| Separate files | [View][fmt_1] |
| Single file    | [View][fmt_2] |
| Interactive    | [View][fmt_3] |
| Mindmap        | [View][fmt_4] |

with the tab key (which, of course, only goes to focusable links and thus always remains in the second column), the spoken word "View" is used to announce each of the four links. It's harder to pick the desired one from four identical announcements. There are other options but, in general, the user would either have to remember a row number, or remember what was announced when they were in a different cell.

Also (less important), the user would hear "table with 4 rows and 2 columns" and this is a bit complex for a situation where a list can be used. GitHub .md files can't be used to satisfy all aspects of accessibility, but I feel that it would be better to replace all tables with approaches similar to:

#### Choose a view

- [View separate files][fmt_1]
- [View single file][fmt_2]
- [View interactive demo][fmt_3]
- [View mindmap][fmt_4]

[fmt_1]: https://github.com/CVEProject/cve-schema/blob/main/schema/CVE_Record_Format.json
[fmt_2]: https://github.com/CVEProject/cve-schema/blob/main/schema/docs/CVE_Record_Format_bundled.json
[fmt_3]: https://cveproject.github.io/cve-schema/schema/docs/
[fmt_4]: https://cveproject.github.io/cve-schema/schema/docs/mindmap.html

@alilleybrinker
Copy link
Author

Thanks, that's great feedback! I hadn't considered the impact of the table-based approach on screen reader accessibility and that's absolutely an oversight on my part. I really appreciate it, and will update the PR to replace the tables.

This amends the `README.md` file to be clearer to navigate.
This is achieved in several ways:

- All links are now hyperlinks on explanatory text, instead of
  bare URLs.
- Where appropriate, information has been gathered into tables.
- How to participate in the QWG and contribute in the repository
  has been spelled out explicitly.
- The distinction between the "production" and "development"
  versions of the format have been clearer by being split into
  distinct sections.

Signed-off-by: Andrew Lilley Brinker <[email protected]>
@alilleybrinker alilleybrinker force-pushed the alilleybrinker/update-readme branch from 262dc3e to 230548a Compare April 30, 2025 15:50
@alilleybrinker
Copy link
Author

@ElectricNroff, I've made the changes you suggested to remove the tables. Thanks again!

@alilleybrinker
Copy link
Author

Note to self, I need to add Dave Waltermire to the list of chairs in the README.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants