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

Improve README #211

Merged
merged 3 commits into from
Aug 25, 2020
Merged

Improve README #211

merged 3 commits into from
Aug 25, 2020

Conversation

Marcono1234
Copy link
Contributor

Notable changes:

  • Consistently capitalize Java, Zip4j, GitHub, API
  • Consistently lowercase zip
  • Fix spelling mistakes
  • Don't format "Features" section as code block
  • Change time span references (e.g. "10 years back") to absolute years (e.g. "back in 2009") to prevent them becoming incorrect in the next year

Additionally in my opinion it would be good to change all links to inline links ([link text](https://example.com)) instead of using link references (except maybe link 7 which is used twice) because it is rather inconvenient when editing the README to have to look at the end of the file to find out where a link leads to.

Maybe for "CP437" it might also make sense to add a link to the Wikipedia article?

@srikanth-lingala
Copy link
Owner

Thanks again for improving the documentation.

Regarding your point about having links inline within documentation (and not as numbered links at the bottom), it is probably a matter of taste, but to me having numbered links makes the text more readable when editing. I understand your point that you have to scroll to the top and the bottom to see where it is pointing to, but links are mostly changed quite rarely, but editing the documentation is done a bit more often, and IMO, makes the text a bit more readable when editing.

@Marcono1234
Copy link
Contributor Author

No problem.

When you merged master into this branch, it added the code block formatting to the "Features" section again. Is that intended or should I revert it?

@srikanth-lingala
Copy link
Owner

@Marcono1234

When you merged master into this branch, it added the code block formatting to the "Features" section again. Is that intended or should I revert it?

No, that was not intended. I will revert it.

I resolved conflicts and will merge this PR now, and will revert the Features formatting again.

@srikanth-lingala srikanth-lingala merged commit e254069 into srikanth-lingala:master Aug 25, 2020
@srikanth-lingala
Copy link
Owner

I just checked the README on master and the features block has ``` and not ~~~.

@Marcono1234
Copy link
Contributor Author

Thanks for merging it. Though my point was that (regardless of whether ``` or ~~~ is used for that section) the "Features" section should in my opinion not be a code block. I don't see any advantages in that, it is rather confusing and decreases readiblity.

@Marcono1234 Marcono1234 deleted the patch-3 branch August 25, 2020 18:19
@srikanth-lingala
Copy link
Owner

Yes, I remember our discussion now. I guess the reason why I had it in the first place was to highlight the block, and that was a noob way of doing it. I just edited it and I agree that it looks better without the code formatting. I will remove it.

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