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 English, Markdown, and clarity in README #791

Merged
merged 2 commits into from
Dec 4, 2024

Conversation

dandv
Copy link
Contributor

@dandv dandv commented Dec 4, 2024

Priority*

  • Medium: This PR should be merged quickly to prevent conflicts due to common changes.

Purpose of the PR*

Thank you for publishing this boilerplate! As a new user, I was mindful of the onboarding process and I contributed a number of fixes that should help future users get started faster and with more clarity as to what various pars of the boilerplate do.

Changes*

  • explain how to change the extension version
  • add warning about restricting permissions to respect users' privacy in production
  • clarify pages usage
  • fix English grammar in sections I had to understand in order to use the boilerplate (this doesn't mean that unchanged sections are correct; just that I didn't get to change them, or that they were too confusing at this stage - see Notes
  • update Chrome Extensions URLs (many pointed to mv3)
  • link pages to their directories
  • remove superfluous Markdown section anchors that are generated automatically by GitHub with the same a name
  • fix abused Markdown formatting with more appropriate version
  • reordered References section with the Chrome Extensions first; Vite is an implementation details of secondary importance

Notes

Some aspects that could be further clarified:

  1. What is the difference between the content and content-ui pages?
  2. Why are some files repeated, e.g. pages/content/public/logo.svg is also found in /pages/content-ui/public/logo.svg
  3. The "Install dependency for turborepo" section. New users may not be familiar with Turborepo, and even after reading about it, it seems like an implementation detail, yet here it gets an entire section. What exactly are "for root" and "for module" in that section?
  4. The "TIP" about sharing state seems to belong towards the end of the page; it's a detail rather than the main screenshot for the boilerplate. It could be replaced with a screenshot showing most of the features at the same time (content script UI at the bottom of a page, the side panel, the action pop-up, a new tab in a separate window)

@dandv dandv requested a review from Jonghakseo as a code owner December 4, 2024 10:37
@Jonghakseo
Copy link
Owner

Thank you for the many corrections and suggestions to the documentation.
I'll make sure to add clarity where it's needed(including you mentioned).

@Jonghakseo Jonghakseo added the documentation Improvements or additions to documentation label Dec 4, 2024
Copy link
Owner

@Jonghakseo Jonghakseo left a comment

Choose a reason for hiding this comment

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

As a non-native English speaker, I am very happy to have this help.
Thank you very much.

@Jonghakseo Jonghakseo merged commit b3ee73c into Jonghakseo:main Dec 4, 2024
7 checks passed
@dandv dandv deleted the patch-1 branch December 4, 2024 14:41
@dandv
Copy link
Contributor Author

dandv commented Dec 4, 2024

More than happy to help! I'm not a native speaker either :)

@dandv dandv mentioned this pull request Dec 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants