avoid “please“, use “see” instead of “refer to”

Author: jouni

.github/styles/Vaadin/Please.yml

@@ -0,0 +1,6 @@
+extends: existence
+message: "Avoid using “please”. Focus on instructing the reader, instead of pleading."
+ignorecase: true
+level: suggestion
+tokens:
+  - please

.github/styles/Vaadin/ReferTo.yml

@@ -0,0 +1,11 @@
+extends: substitution
+message: "Prefer '%s' over '%s' when linking to another documentation resource."
+level: suggestion
+ignorecase: true
+action:
+  name: replace
+swap:
+  refer to: see
+  please refer to: see
+  check: see
+  please check: see

articles/advanced/browser-access.asciidoc

@@ -23,7 +23,7 @@ For example:
 ----
 UI.getCurrent().getPage().fetchCurrentURL(currentUrl -> {
     // This is your own method that you may do something with the url.
-    // Please note that this method runs asynchronously
+    // Note that this method runs asynchronously
     storeCurrentURL(currentUrl);
 });
 ----
@@ -43,7 +43,7 @@ For example, the following can be used to get the screen width:
 ----
 UI.getCurrent().getPage().retrieveExtendedClientDetails(details -> {
     // This is your own method that you may do something with the screen width.
-    // Please note that this method runs asynchronously
+    // Note that this method runs asynchronously
     handleScreenWidth(details.getScreenWidth());
 });
 ----
@@ -96,4 +96,3 @@ page.addBrowserWindowResizeListener(
 
 [.discussion-id]
 0DF2CC14-4401-49E4-B97D-920CAFEAAF8D
-

articles/advanced/custom-error-handler.asciidoc

@@ -26,7 +26,7 @@ public class CustomErrorHandler implements ErrorHandler {
         if(UI.getCurrent() != null) {
             UI.getCurrent().access(() -> {
                 Notification.show("An internal error has occurred." +
-                        "Please contact support.");
+                        "Contact support for assistance.");
             });
         }
     }
@@ -46,4 +46,3 @@ See the <<session-and-ui-init-listener#,Session and UI Listeners>> article to le
 
 [.discussion-id]
 98746DB3-C9AC-42AD-A43D-D79F09B2155E
-

articles/binding-data/components-binder-beans.asciidoc

@@ -30,7 +30,7 @@ binder.bind(streetAddressField, "address.street");
 binder.forField(yearOfBirthField)
     .withConverter(
         new StringToIntegerConverter(
-                "Please enter a number"))
+                "Enter a number"))
     .bind("yearOfBirth");
 ----
 
@@ -265,4 +265,3 @@ binder.setRequiredConfigurator(
 
 [.discussion-id]
 D8AE5573-0248-4DBC-A58E-CBEA8E8F0957
-

articles/binding-data/components-binder-validation.asciidoc

@@ -242,7 +242,7 @@ binder.forField(yearOfBirthField)
         String::valueOf,
         // Text to use instead of the
         // NumberFormatException message
-        "Please enter a number")
+        "Enter a number")
     .bind(Person::getYearOfBirth,
             Person::setYearOfBirth);
 ----
@@ -363,7 +363,7 @@ public class DatePickerDemo implements HasValidator<LocalDate> /*, HasValue<...>
 ----
 <1> The validator instance returned by [methodname]`getDefaultValidator()` gets called every time the binding instance validates/revalidates (as a part of the validator chain of the binding).
 
-For a complete implementation, please refer to http://github.com/vaadin/flow-components/blob/master/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java[DatePicker's source code] as an example.
+For a complete implementation see, for example, the http://github.com/vaadin/flow-components/blob/master/vaadin-date-picker-flow-parent/vaadin-date-picker-flow/src/main/java/com/vaadin/flow/component/datepicker/DatePicker.java[`DatePicker` source code].
 
 
 [.discussion-id]

articles/components/charts/configuration.asciidoc

@@ -201,8 +201,7 @@ A chart can have more than one Y-axis, usually when different series displayed
 in a graph have different units or scales. The association of a data series with
 an axis is done in the data series object with [methodname]`setyAxis()`.
 
-For a complete reference of the many configuration parameters for the axes,
-please refer to the JavaDoc API documentation of Charts.
+For a complete reference of the many configuration parameters for the axes, see the Charts Javadoc API documentation.
 
 [[charts.configuration.axes.type]]
 === Axis Type
@@ -309,7 +308,7 @@ X offset defaults to 0, but Y to [literal]#++null++#, which enables automatic po
 Gauge, pie, and polar charts allow additional properties.
 
 For a complete reference of the many configuration parameters for the labels,
-please refer to the JavaDoc API documentation of Charts.
+see the Charts Javadoc API documentation.
 
 
 [[charts.configuration.axes.extremes]]
@@ -418,4 +417,3 @@ floating-point precision for the values.
 
 [.discussion-id]
 5FCAE9D2-4CEB-4600-A33D-A6082E36BC4F
-

articles/components/charts/css-styling.asciidoc

@@ -27,7 +27,7 @@ See a <<{articles}/components/charts#,demo of the variants>>.
 
 == Java Styling
 The default styling mode in Flow applications uses the Java API.
-Please see the link:http://vaadin.com/api/platform/com/vaadin/flow/component/charts/model/style/package-summary.html[Java API reference] for details.
+See the link:http://vaadin.com/api/platform/com/vaadin/flow/component/charts/model/style/package-summary.html[Java API reference] for details.
 
 
 [[css.styling]]
@@ -142,4 +142,3 @@ image::img/css-styling2.png[]
 
 [.discussion-id]
 3E5B31FB-DF25-4D1E-80EB-7AB485C7B566
-

articles/components/charts/migrating-from-earlier-versions.asciidoc

@@ -51,7 +51,7 @@ Configuration conf = chart.getConfiguration();
 conf.getChart().setStyledMode(true);
 ----
 
-For more detailed instructions, please check the
+For more detailed instructions, see the
 <<css-styling#,"CSS Styling guide">>
 
 
@@ -94,4 +94,3 @@ on this page.
 
 [.discussion-id]
 CA191212-B228-4F07-9F40-BC0C68F84FA0
-

articles/components/charts/svg-generator.asciidoc

@@ -23,8 +23,9 @@ Add the `vaadin-charts-flow-svg-generator` dependency to your project's `pom.xml
 ----
 
 .Node.js required
-NOTE: Node.js must be installed for the generator to work.
-Please see the configuration instructions in <<{articles}/configuration/node-js#,Installing Node.js>>.
+[NOTE]
+Node.js must be installed for the generator to work.
+See the configuration instructions in <<{articles}/configuration/node-js#,Installing Node.js>>.
 
 == Using the Generator
 
@@ -126,4 +127,3 @@ add(div);
 
 [.discussion-id]
 C8510402-621D-437D-ADD9-E219BBDB532D
-