Converted the readme to markdown for accessibility - #362
Merged
Merged
Conversation
… notes, which are only divided into headings for now
Contributor
|
This all looks good to me! The one change I'd request is adding a line to the changelog mentioning converting the README to Markdown. |
Contributor
Author
|
Done! I classified it as "Documentation" as I wasn't sure what else it should be. Lemme know if that's wrong. :7 |
Contributor
|
Looks good to me! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Plain text files are difficult to skim with a screenreader, because they contain no semantic information. A readme is the type of file one often needs to skim, to find platform-specific build instructions, website links, release notes, etc. Because markdown can be rendered as semantic HTML, it is inherently more accessible to screenreaders, and possibly more user friendly to those less familiar with GitHub. I manually converted the whole repo readme to markdown, flattening indented lines according to the style I know and use. The biggest changes are turning the section titles into headings, and making the directory structure into a table.
I used minimal emphasis, partly to avoid the LLM flavor, mostly because it was plain text to begin with and I didn't want to unintentionally change any meanings. I only emphasized text where a previously indented line seemed to be doing so.
I didn't format the release notes at all, beyond giving each version a heading at level 3, and Linus's library bugfixes/releases at level 4. This is for the reasons already mentioned, and also because it's a lot of text to format by hand, although I want to for completionist reasons. I do think the release notes would be better off in a separate document, linked to by the readme, but that's an issue for another issue.