Khan / engblog

KA Engineering blog.
http://engineering.khanacademy.org
Other
29 stars 20 forks source link

Fix a few typos #74

Closed jdkato closed 6 years ago

jdkato commented 6 years ago

These were found by Vale, which was mentioned as a candidate for https://github.com/Khan/engblog/issues/51. If you're interested, I could submit another PR that adds Vale to your CI build.

The PR would include the following:

  1. A .vale.ini file configured to lint Markdown and reStructuredText documents, excluding front matter and math (both $$ … $$ and $ … $);
  2. a custom vocabulary file that you can add to as you encounter words that Vale doesn't recognize; and
  3. a simple engblog style to catch common capitalization mistakes like "Javascript" instead of "JavaScript."

For what it's worth, Linode and Write the Docs have been using Vale in a similar capacity for a few months now.

jdkato commented 6 years ago

I addressed your change requests in 23dbfccc1f75b8b4c5aa8593722de7539a1a94a5.

As for Vale itself, it's really not a grammar checker—it's much more like traditional source code linters. In other words, outside of simple things like spelling and repetition, Vale focuses on stylistic errors (e.g., branding, heading styles, word choice, etc.) rather than grammatical or structural errors.

Anyways, with the configuration I mentioned above, this was Vale's exact output:

Vale output

```console $ vale --glob='*.{md,rst}' src/posts/ src/posts/creating-query-components-with-apollo.md 14:49 warning 'in' is repeated! vale.Repetition src/posts/copy-pasting-more-than-just-text.md 64:61 error Use 'JavaScript' instead of engblog.Terms 'Javascript'. 97:36 error Use 'JavaScript' instead of engblog.Terms 'Javascript'. src/posts/evolving-our-content-infrastructure.md 398:56 warning 'had' is repeated! vale.Repetition src/posts/fun-with-slopfields.md 75:280 error Did you really mean engblog.Spelling 'efectively'? src/posts/lets-reduce.md 21:83 error Use 'JavaScript' instead of engblog.Terms 'Javascript'. 211:1 error Use 'JavaScript' instead of engblog.Terms 'Javascript'. src/posts/memcached-fms.md 41:637 warning 'very' is repeated! vale.Repetition src/posts/new-employees-primer.md 87:9 warning 'ship' is repeated! vale.Repetition src/posts/new-oss-activity.md 17:88 error Did you really mean engblog.Spelling 'dependancy'? 17:150 warning 'which' is repeated! vale.Repetition 30:416 error Did you really mean engblog.Spelling 'dyanamic'? 30:425 error Did you really mean engblog.Spelling 'prorogramming'? src/posts/python-refactor-3.md 85:45 warning 'from' is repeated! vale.Repetition src/posts/react-native-monorepo.md 187:24 error Did you really mean engblog.Spelling 'suprised'? src/posts/receiving-feedback.md 27:463 warning 'that' is repeated! vale.Repetition src/posts/snippet-server.md 23:1 error Use 'JavaScript' instead of engblog.Terms 'javascript'. 159:55 warning 'low' is repeated! vale.Repetition ```


With regards to how it can be used, the basic idea would be to have it run via Travis CI (and cause the build to fail on error-level alerts) whenever you make content changes to src/posts. It would have caught most of these (outside of "an" and "its").

csilvers commented 6 years ago

Well, I'm not sure exactly what "word choice" it would be unhappy with, but I definitely have no problem with the fixes it proposed here. Thanks for making them!

Let's continue the discussion about whether to install vale on that issue.