Add write-good linting

docs/.textlintrc.js

@@ -3,14 +3,17 @@ module.exports = {
   rules: {
     'common-misspellings': true,
     'en-capitalization': true,
-    terminology: {
-      defaultTerms: false,
-      terms: `${__dirname}/.textlint.terms.json`,
-    },
     'stop-words': {
       exclude: [
         'relative to', // We need to talk about links "relative to the root"
       ],
     },
+    terminology: {
+      defaultTerms: false,
+      terms: `${__dirname}/.textlint.terms.json`,
+    },
+    'write-good': {
+      passive: false,
+    },
   },
 };

docs/README.md

@@ -16,7 +16,8 @@ It will read all source files in `./src` and build the final static website in
 ### Local development
 
 You can run a local copy of the documentation website by running `yarn run
-serve` in this directory or `yarn run docs:serve` at the repository root.
+serve`. This is an alias for running `yarn run docs:serve` at the repository
+root.
 
 This will build the website in `./dist` and expose it on `localhost`, along with
 live-reload.

docs/package.json

@@ -68,7 +68,8 @@
     "textlint-rule-common-misspellings": "^1.0.1",
     "textlint-rule-en-capitalization": "^2.0.1",
     "textlint-rule-stop-words": "^1.0.4",
-    "textlint-rule-terminology": "^1.1.29"
+    "textlint-rule-terminology": "^1.1.29",
+    "textlint-rule-write-good": "^1.6.2"
   },
   "peerDependencies": {},
   "dependencies": {

docs/src/config-file.md

@@ -380,13 +380,13 @@ is set to the number of records that were extracted and indexed. We check this
 key internally to keep track of any unintended spike or drop that could reveal
 a misconfiguration.
 
-You don't have to touch, we're documenting it here in case you were
+You don't have to touch it, we're documenting it here in case you were
 wondering what this was about.
 
 ### `only_content_level` _Optional_
 
 When `only_content_level` is set to `true`, then the crawler won't create
-records for each `lvlX` selectors, but only for the `text` selectors.
+records for the `lvlX` selectors.
 
 If used, `min_indexed_level` is ignored.
 

docs/src/crawler-overview.md

@@ -18,11 +18,11 @@ behave. You can find the complete list of options in [our documentation][2].
 
 We automatically run each config every 24h. This is done from our own
 infrastructure, meaning that you don't need to install anything on your side.
-We run this service entirely free of charge, we're just asking that you keep the
+We run this service entirely free of charge, but we're asking that you keep the
 "powered by Algolia" logo next to the search results.
 
 That being said, if you'd like to run DocSearch on your own, [all the code is
-open source][3] and even packaged as a Docker image. Just grab it, and run it
+open source][3] and even packaged as a Docker image. Download it, and run it
 with your own credentials.
 
 [1]: https://scrapy.org/

docs/src/inside-the-engine.md

@@ -41,11 +41,10 @@ then fallback to partial matches. Those results will then be ordered based, once
 again, on the page hierarchy, as extracted from the `selectors`.
 
 The default strategy is to first look at the closest header of the matching
-text. If a matching paragraph of text is under `Advanced Settings / API Options
-/ verySpecificMethod()`, it will be ranked higher than if it is only found under
-`Gettings Started > Installation`. The idea here is that if you have a match
-under a very deep hierarchy, chances are that this match is very specific and
-might be more interesting that something found in a very broad topic.
+text. For example, a paragraph under `Settings / API / verySpecificMethod()`,
+will be ranked higher than one under `Settings / API`.  The idea here is that if
+you have a match under a deep hierarchy, chances are that this match is specific
+and might be more interesting that something found in a broad topic.
 
 But this does not work in all cases as some documentations don't have deep
 hierarchy. In that case, we use the paragraph position. The first paragraph of

docs/src/tips.md

@@ -41,10 +41,9 @@ class="title-X">` for example instead. Your crawling configuration file will
 
 ### Set a unique class to the element holding the content
 
-As DocSearch is extracting content based on the HTML structure, it is important
-to narrow its results to only the relevant content. In that regard, we
-recommend that you add a custom `id` to the HTML element that will be the parent
-of all your textual content.
+DocSearch is extracting content based on the HTML structure. We recommend that
+you add a custom `class` to the HTML element wrapping all your textual content.
+This will help narrow selectors to the relevant content.
 
 Having such a unique identifier will make your configuration more robust as it
 will make sure all indexed content is relevant content. We found that

docs/src/what-is-docsearch.md

@@ -4,27 +4,27 @@ title: What is DocSearch?
 ---
 
 DocSearch is born out of the need to scratch our own itch. As developers, we
-spent a lot of time reading documentation, and we often found it hard to find
-relevant information we need quickly. We're not blaming anyone here; building
+spent a lot of time reading documentation, and it can be hard to find relevant
+information in large documentations. We're not blaming anyone here; building
 a good search is a challenge.
 
-It just happens that we are a search company and we actually have a lot of
+It happens that we are a search company and we actually have a lot of
 experience building search interfaces. We wanted to use those skills to help
 others. That's why we created a way to automatically extract content from tech
-documentation and make it available to everyone with only a few keystrokes.
+documentation and make it available to everyone from the first keystroke.
 
 DocSearch itself is made of a crawler and a frontend library. We run the
 crawler on our end every 24h to extract content from your website and push it to
 an Algolia index. You'll then have to add the frontend library to your website
 to redirect all the search requests to this index.
 
-DocSearch is entirely free and mostly automated. The only thing we'll need from
+DocSearch is entirely free and automated. The one thing we'll need from
 you is to read [our checklist][2] and apply! After that, we'll share with you
-the JavaScript snippet needed to add DocSearch to your website. We just ask that
+the JavaScript snippet needed to add DocSearch to your website. We ask that
 you keep the "powered by Algolia" link displayed.
 
-DocSearch is [one of our ways][1] to give back
-to the open source community for everything it did for us already.
+DocSearch is [one of our ways][1] to give back to the open source community for
+everything it did for us already.
 
 [1]: https://opencollective.com/algolia
 

docs/src/who-can-apply.md

@@ -3,9 +3,9 @@ layout: two-columns
 title: Who can apply?
 ---
 
-DocSearch has been built from the ground up with the idea of improving search on
-large technical documentation. For that reason, we only provide the free hosting
-version to technical documentation websites.
+DocSearch was built from the ground up with the idea of improving search on
+large technical documentation. For that reason, we offering our free hosting
+version to all technical documentations.
 
 We're always sad to have to turn down applications, but with the number of
 requests we received everyday, we had to focus on technical documentations.
@@ -38,8 +38,8 @@ features of Algolia.
 
 ### Priority
 
-We're receiving many requests every day, and while we strive to answer them all
-as fast as we can, we sometimes give priority to some of them based on the
+We're receiving dozens of requests every day, and while we strive to answer them
+all as fast as we can, we sometimes give priority to some of them based on the
 following criteria:
 
 - 🙂 If your project is open source, We'll handle it before any other
@@ -50,7 +50,7 @@ following criteria:
 
 - ☹️ If your website is rendered in the browser through JavaScript, it means that
   we'll have to crawl it through a much slower browser emulation. We highly
-  recommend that you implement server-side rendering if you can.
+  recommend that you put in place server-side rendering if you can.
 
 [1]: ./apply.html