Skip to content

Conversation

@alilleybrinker
Copy link
Contributor

@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
Contributor 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.

@alilleybrinker alilleybrinker force-pushed the alilleybrinker/update-readme branch from 262dc3e to 230548a Compare April 30, 2025 15:50
@alilleybrinker
Copy link
Contributor Author

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

@alilleybrinker
Copy link
Contributor Author

alilleybrinker commented May 1, 2025

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

EDIT: Done, added Dave.

@alilleybrinker alilleybrinker changed the title Update README.md to be clearer. Update README.md to be clearer May 7, 2025
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 230548a to 52e22c5 Compare May 7, 2025 20:47
@ccoffin ccoffin merged commit 9725cf5 into CVEProject:develop May 20, 2025
1 check passed
@alilleybrinker alilleybrinker deleted the alilleybrinker/update-readme branch May 20, 2025 17:17
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.

4 participants