From 4dc998f01b1c81d568bb7e0bcc8db79d4d9d56b9 Mon Sep 17 00:00:00 2001 From: Pixelastic Date: Fri, 24 Aug 2018 13:15:02 +0200 Subject: [PATCH] Add write-good linting --- docs/.textlintrc.js | 11 +++++++---- docs/README.md | 3 ++- docs/package.json | 3 ++- docs/src/config-file.md | 4 ++-- docs/src/crawler-overview.md | 4 ++-- docs/src/inside-the-engine.md | 9 ++++----- docs/src/tips.md | 7 +++---- docs/src/what-is-docsearch.md | 16 ++++++++-------- docs/src/who-can-apply.md | 12 ++++++------ 9 files changed, 36 insertions(+), 33 deletions(-) diff --git a/docs/.textlintrc.js b/docs/.textlintrc.js index 7c4ef1fc..0f6602f5 100644 --- a/docs/.textlintrc.js +++ b/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, + }, }, }; diff --git a/docs/README.md b/docs/README.md index b1957b13..5ef56110 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/package.json b/docs/package.json index 15c0ffbe..93181974 100644 --- a/docs/package.json +++ b/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": { diff --git a/docs/src/config-file.md b/docs/src/config-file.md index 64480dd4..538e0cca 100644 --- a/docs/src/config-file.md +++ b/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. diff --git a/docs/src/crawler-overview.md b/docs/src/crawler-overview.md index e3968be0..8fbb0ef0 100644 --- a/docs/src/crawler-overview.md +++ b/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/ diff --git a/docs/src/inside-the-engine.md b/docs/src/inside-the-engine.md index 28bc4903..b1bfa33a 100644 --- a/docs/src/inside-the-engine.md +++ b/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 diff --git a/docs/src/tips.md b/docs/src/tips.md index 9fd1f30c..639dc8ad 100644 --- a/docs/src/tips.md +++ b/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 diff --git a/docs/src/what-is-docsearch.md b/docs/src/what-is-docsearch.md index a871b4ab..7d9d3d0f 100644 --- a/docs/src/what-is-docsearch.md +++ b/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 diff --git a/docs/src/who-can-apply.md b/docs/src/who-can-apply.md index a5a7f3f8..db7a1e84 100644 --- a/docs/src/who-can-apply.md +++ b/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