Skip to content

Small readme improvements, remove the word "simple" #2671

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

Merged
merged 6 commits into from
Dec 16, 2018
Merged

Small readme improvements, remove the word "simple" #2671

merged 6 commits into from
Dec 16, 2018

Conversation

robwierzbowski
Copy link
Contributor

Most of us are reading the docs because we don't know how to do something, and it's not fun to hear that the concept we're having a hard time understanding is "simple" or "easy". I'd love you to show me how simple it is instead.

A great reference: https://css-tricks.com/words-avoid-educational-writing/

Updated some language around contenthash as well, hopefully it's a little more direct. Let me know what you think.

Most of us are reading the docs because we don't know how to do something, and it's not fun to hear that the concept we're having a hard time understanding is "simple" or "easy". I'd love you to show me how simple it is instead. 

A great reference: https://css-tricks.com/words-avoid-educational-writing/

Updated some language around `contenthash` as well, hopefully it's a little more direct. Let me know what you think.
Copy link
Member

@montogeek montogeek left a comment

Choose a reason for hiding this comment

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

Just a typo according to our Brand guidelines.
Thanks!

@@ -24,7 +24,7 @@ This guide focuses on the configuration needed to ensure files produced by webpa

## Output Filenames

A simple way to ensure the browser picks up changed files is by using `output.filename` [substitutions](/configuration/output#output-filename). The `[hash]` substitution can be used to include a build-specific hash in the filename, however it's even better to use the `[contenthash]` substitution which is the hash of the content of a file, which is different for each asset.
We can use the `output.filename` [substitutions](/configuration/output#output-filename) setting to define the names of our output files. Webpack provides a method of templating the filenames using bracketed strings called **substitutions**. The `[contenthash]` substitution will add a unique hash based on the content of an asset. When the asset's content changes, `[contenthash]` will change as well.
Copy link
Member

Choose a reason for hiding this comment

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

Please use webpack

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Switched this and another instance in the file.

@montogeek
Copy link
Member

Agree, nothing is simple or just, if you find more occurrences, please feel free to submit a PR changing them.

@robwierzbowski
Copy link
Contributor Author

Thanks! I have noticed other occurrences, but probably won't have time in the near future to edit. I did this page because I'm about to send some colleagues here 😄.

Copy link
Member

@EugeneHlushko EugeneHlushko left a comment

Choose a reason for hiding this comment

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

please update boldness style and its good to me

@@ -24,7 +24,7 @@ This guide focuses on the configuration needed to ensure files produced by webpa

## Output Filenames

A simple way to ensure the browser picks up changed files is by using `output.filename` [substitutions](/configuration/output#output-filename). The `[hash]` substitution can be used to include a build-specific hash in the filename, however it's even better to use the `[contenthash]` substitution which is the hash of the content of a file, which is different for each asset.
We can use the `output.filename` [substitutions](/configuration/output#output-filename) setting to define the names of our output files. webpack provides a method of templating the filenames using bracketed strings called **substitutions**. The `[contenthash]` substitution will add a unique hash based on the content of an asset. When the asset's content changes, `[contenthash]` will change as well.
Copy link
Member

Choose a reason for hiding this comment

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

We are using __ for boldness. Please use it here for consistency:

Suggested change
We can use the `output.filename` [substitutions](/configuration/output#output-filename) setting to define the names of our output files. webpack provides a method of templating the filenames using bracketed strings called **substitutions**. The `[contenthash]` substitution will add a unique hash based on the content of an asset. When the asset's content changes, `[contenthash]` will change as well.
We can use the `output.filename` [substitutions](/configuration/output#output-filename) setting to define the names of our output files. webpack provides a method of templating the filenames using bracketed strings called __substitutions__. The `[contenthash]` substitution will add a unique hash based on the content of an asset. When the asset's content changes, `[contenthash]` will change as well.

Doesnt markdown lint throw for you when you lint it?

@EugeneHlushko
Copy link
Member

yeap lint fails, make sure that lint passes before you push

@robwierzbowski
Copy link
Contributor Author

robwierzbowski commented Nov 30, 2018 via email

@EugeneHlushko
Copy link
Member

If you have difficulties @robwierzbowski please let me know

@robwierzbowski
Copy link
Contributor Author

Formatting updates made. lint:social threw warnings not related to this page. It did fail locally as well, but with an unrelated lifecycle error. Hopefully it passes on CI.

@montogeek
Copy link
Member

Please fix this error:

src/content/guides/caching.md:341:91: skunked_terms.misc 'Hopefully' is a bit of a skunked term — impossible to use without issue. Find some other way to say it.

Weasel word, and the statement doesn't really give value.
@robwierzbowski
Copy link
Contributor Author

robwierzbowski commented Dec 3, 2018

Proselint isn't installed locally -- you might want to install that as a dev dependency so users don't have to install globally. I would install but proselint triggers npm vulnerability warnings, don't know how you want to handle that. I'm also getting lint:social errors on a fresh clone and install:

⚠ 27 warnings
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! [email protected] lint:social: `alex . -q`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the [email protected] lint:social script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/RobW/.npm/_logs/2018-12-03T19_56_14_842Z-debug.log

Update to remove However. Let me know if you'd like me to do anything else!

@montogeek montogeek merged commit 99b0355 into webpack:master Dec 16, 2018
@montogeek
Copy link
Member

Thanks!

EugeneHlushko added a commit that referenced this pull request Dec 17, 2018
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants