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

[Docs] Improve README.md & CONTRIBUTING.md syntax #1864

Merged
merged 1 commit into from
Nov 6, 2018

Conversation

PeterDaveHello
Copy link
Collaborator

There are four kinds of changes in this PR in a single commit:

  • Lists should be surrounded by blank lines
  • Use only 1. for ordered list item prefix
  • Starting bulleted lists at the beginning of the line
  • Fenced code blocks should be surrounded by blank lines

This improvement helps maintain the consistency in the document and the maintainability, readability in the document source.

- Lists should be surrounded by blank lines
- Use only `1.` for ordered list item prefix
- Starting bulleted lists at the beginning of the line
- Fenced code blocks should be surrounded by blank lines
@PeterDaveHello PeterDaveHello changed the title [Docs] Improve README.md syntax [Docs] Improve README.md & CONTRIBUTING.md syntax Jul 14, 2018
@PeterDaveHello
Copy link
Collaborator Author

@ljharb anything else I need to do here? Thanks.

CONTRIBUTING.md Outdated
@@ -5,14 +5,16 @@ We love pull requests and issues, they're our favorite.
However, before submitting, please review the following:

For bug reports:
- Please make sure the bug is reproducible, and give us the steps to reproduce it, so that we can dig into the problem.
Copy link
Member

Choose a reason for hiding this comment

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

i'm confused why this is an improvement; it seems like it'd render the same in the markdown, but it's much less readable in raw form.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

It's suggested by the markdownlint tool:
https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#md006---consider-starting-bulleted-lists-at-the-beginning-of-the-line, the lists should start at the beginning of the lines, sounds reasonable?

Copy link
Member

Choose a reason for hiding this comment

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

No, i don’t agree with that rationale - i don’t care about the editing experience, but the reading experience in raw form is important to me.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

okay, I'll rollback this one, how about the others? Look good to you?

Copy link
Member

Choose a reason for hiding this comment

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

i think so; i'll take another look once the diff is updated

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I have a concern here, some of them, including the table of contents, start from the beginning of the lines, won't this make some inconsistency? and in that case of table of contents, it looks different.

Let me know if I should just "rollback" or the consistency should also be maintained, thanks.

Copy link
Member

Choose a reason for hiding this comment

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

i guess i'm not sure i see a need for consistency between all lists - lists that are top-level things like a TOC are one thing, and lists that are subpoints of another paragraph are another.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Okay, I'll just rollback those changes.

@PeterDaveHello
Copy link
Collaborator Author

@ljharb are we good to go now? Thanks.

@ljharb ljharb merged commit f3fd5ef into nvm-sh:master Nov 6, 2018
@PeterDaveHello PeterDaveHello deleted the Improve-README.md-format branch November 6, 2018 07:16
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.

2 participants