doc: remove "it is important to" phrasing

Instead of telling someone "It is important to do X", just tell them to
"Do X."

PR-URL: https://github.com/nodejs/node/pull/30108
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

doc/api/addons.md

@@ -364,13 +364,12 @@ and load it instead.
 ## Native Abstractions for Node.js
 
 Each of the examples illustrated in this document make direct use of the
-Node.js and V8 APIs for implementing Addons. It is important to understand
+Node.js and V8 APIs for implementing Addons. The V8 API can, and has, changed
-that the V8 API can, and has, changed dramatically from one V8 release to the
+dramatically from one V8 release to the next (and one major Node.js release to
-next (and one major Node.js release to the next). With each change, Addons may
+the next). With each change, Addons may need to be updated and recompiled in
-need to be updated and recompiled in order to continue functioning. The Node.js
+order to continue functioning. The Node.js release schedule is designed to
-release schedule is designed to minimize the frequency and impact of such
+minimize the frequency and impact of such changes but there is little that
-changes but there is little that Node.js can do currently to ensure stability
+Node.js can do currently to ensure stability of the V8 APIs.
-of the V8 APIs.
 
 The [Native Abstractions for Node.js][] (or `nan`) provide a set of tools that
 Addon developers are recommended to use to keep compatibility between past and

doc/api/child_process.md

@@ -361,7 +361,7 @@ returned [`ChildProcess`][] will have an additional communication channel
 built-in that allows messages to be passed back and forth between the parent and
 child. See [`subprocess.send()`][] for details.
 
-It is important to keep in mind that spawned Node.js child processes are
+Keep in mind that spawned Node.js child processes are
 independent of the parent with exception of the IPC communication channel
 that is established between the two. Each process has its own memory, with
 their own V8 instances. Because of the additional resource allocations
@@ -955,7 +955,7 @@ The `'error'` event is emitted whenever:
 3. Sending a message to the child process failed.
 
 The `'exit'` event may or may not fire after an error has occurred. When
-listening to both the `'exit'` and `'error'` events, it is important to guard
+listening to both the `'exit'` and `'error'` events, guard
 against accidentally invoking handler functions multiple times.
 
 See also [`subprocess.kill()`][] and [`subprocess.send()`][].

doc/api/crypto.md

@@ -1707,8 +1707,8 @@ Initialization vectors should be unpredictable and unique; ideally, they will be
 cryptographically random. They do not have to be secret: IVs are typically just
 added to ciphertext messages unencrypted. It may sound contradictory that
 something has to be unpredictable and unique, but does not have to be secret;
-it is important to remember that an attacker must not be able to predict ahead
+remember that an attacker must not be able to predict ahead of time what a
-of time what a given IV will be.
+given IV will be.
 
 ### crypto.createDecipher(algorithm, password\[, options\])
 <!-- YAML
@@ -1801,8 +1801,8 @@ Initialization vectors should be unpredictable and unique; ideally, they will be
 cryptographically random. They do not have to be secret: IVs are typically just
 added to ciphertext messages unencrypted. It may sound contradictory that
 something has to be unpredictable and unique, but does not have to be secret;
-it is important to remember that an attacker must not be able to predict ahead
+remember that an attacker must not be able to predict ahead of time what a given
-of time what a given IV will be.
+IV will be.
 
 ### crypto.createDiffieHellman(prime\[, primeEncoding\]\[, generator\]\[, generatorEncoding\])
 <!-- YAML

doc/api/dgram.md

@@ -466,7 +466,7 @@ client.send([buf1, buf2], 41234, (err) => {
 ```
 
 Sending multiple buffers might be faster or slower depending on the
-application and operating system. It is important to run benchmarks to
+application and operating system. Run benchmarks to
 determine the optimal strategy on a case-by-case basis. Generally speaking,
 however, sending multiple buffers is faster.
 

doc/api/events.md

@@ -43,7 +43,7 @@ myEmitter.emit('event');
 ## Passing arguments and `this` to listeners
 
 The `eventEmitter.emit()` method allows an arbitrary set of arguments to be
-passed to the listener functions. It is important to keep in mind that when
+passed to the listener functions. Keep in mind that when
 an ordinary listener function is called, the standard `this` keyword
 is intentionally set to reference the `EventEmitter` instance to which the
 listener is attached.
@@ -77,8 +77,8 @@ myEmitter.emit('event', 'a', 'b');
 ## Asynchronous vs. Synchronous
 
 The `EventEmitter` calls all listeners synchronously in the order in which
-they were registered. This is important to ensure the proper sequencing of
+they were registered. This ensures the proper sequencing of
-events and to avoid race conditions or logic errors. When appropriate,
+events and helps avoid race conditions and logic errors. When appropriate,
 listener functions can switch to an asynchronous mode of operation using
 the `setImmediate()` or `process.nextTick()` methods:
 

doc/api/n-api.md

@@ -810,11 +810,11 @@ When an exception is pending one of two approaches can be employed.
 
 The first approach is to do any appropriate cleanup and then return so that
 execution will return to JavaScript. As part of the transition back to
-JavaScript the exception will be thrown at the point in the JavaScript
+JavaScript, the exception will be thrown at the point in the JavaScript
 code where the native method was invoked. The behavior of most N-API calls
 is unspecified while an exception is pending, and many will simply return
-`napi_pending_exception`, so it is important to do as little as possible
+`napi_pending_exception`, so do as little as possible and then return to
-and then return to JavaScript where the exception can be handled.
+JavaScript where the exception can be handled.
 
 The second approach is to try to handle the exception. There will be cases
 where the native code can catch the exception, take the appropriate action,
@@ -4344,8 +4344,7 @@ required in order to enable correct disposal of the reference.
 Addon modules often need to leverage async helpers from libuv as part of their
 implementation. This allows them to schedule work to be executed asynchronously
 so that their methods can return in advance of the work being completed. This
-is important in order to allow them to avoid blocking overall execution
+allows them to avoid blocking overall execution of the Node.js application.
-of the Node.js application.
 
 N-API provides an ABI-stable interface for these
 supporting functions which covers the most common asynchronous use cases.
@@ -4948,9 +4947,9 @@ Upon creation of a `napi_threadsafe_function` a `napi_finalize` callback can be
 provided. This callback will be invoked on the main thread when the thread-safe
 function is about to be destroyed. It receives the context and the finalize data
 given during construction, and provides an opportunity for cleaning up after the
-threads e.g. by calling `uv_thread_join()`. **It is important that, aside from
+threads e.g. by calling `uv_thread_join()`. **Aside from the main loop thread,
-the main loop thread, there be no threads left using the thread-safe function
+no threads should be using the thread-safe function after the finalize callback
-after the finalize callback completes.**
+completes.**
 
 The `context` given during the call to `napi_create_threadsafe_function()` can
 be retrieved from any thread with a call to
@@ -4995,13 +4994,13 @@ existing thread will stop making use of the thread-safe function.
 the object has called `napi_release_threadsafe_function()` or has received a
 return status of `napi_closing` in response to a call to
 `napi_call_threadsafe_function`. The queue is emptied before the
-`napi_threadsafe_function` is destroyed. It is important that
+`napi_threadsafe_function` is destroyed. `napi_release_threadsafe_function()`
-`napi_release_threadsafe_function()` be the last API call made in conjunction
+should be the last API call made in conjunction with a given
-with a given `napi_threadsafe_function`, because after the call completes, there
+`napi_threadsafe_function`, because after the call completes, there is no
-is no guarantee that the `napi_threadsafe_function` is still allocated. For the
+guarantee that the `napi_threadsafe_function` is still allocated. For the same
-same reason it is also important that no more use be made of a thread-safe
+reason, do not make use of a thread-safe function
-function after receiving a return value of `napi_closing` in response to a call
+after receiving a return value of `napi_closing` in response to a call to
-to `napi_call_threadsafe_function`. Data associated with the
+`napi_call_threadsafe_function`. Data associated with the
 `napi_threadsafe_function` can be freed in its `napi_finalize` callback which
 was passed to `napi_create_threadsafe_function()`.
 

doc/api/stream.md

@@ -100,7 +100,7 @@ maintaining an appropriate and efficient flow of data. For example,
 [`net.Socket`][] instances are [`Duplex`][] streams whose `Readable` side allows
 consumption of data received *from* the socket and whose `Writable` side allows
 writing data *to* the socket. Because data may be written to the socket at a
-faster or slower rate than data is received, it is important for each side to
+faster or slower rate than data is received, each side should
 operate (and buffer) independently of the other.
 
 ## API for Stream Consumers
@@ -1658,11 +1658,11 @@ class MyWritable extends Writable {
 }
 ```
 
-When extending streams, it is important to keep in mind what options the user
+When extending streams, keep in mind what options the user
 can and should provide before forwarding these to the base constructor. For
-example, if the implementation makes assumptions in regard to e.g. the
+example, if the implementation makes assumptions in regard to the
-`autoDestroy` and `emitClose` options, it becomes important to not allow the
+`autoDestroy` and `emitClose` options, do not allow the
-user to override these. It is therefore recommended to be explicit about what
+user to override these. Be explicit about what
 options are forwarded instead of implicitly forwarding all options.
 
 The new stream class must then implement one or more specific methods, depending
@@ -2609,8 +2609,8 @@ readable.on('data', (chunk) => {
 
 #### Piping to Writable Streams from Async Iterators
 
-In the scenario of writing to a writable stream from an async iterator,
+In the scenario of writing to a writable stream from an async iterator, ensure
-it is important to ensure the correct handling of backpressure and errors.
+the correct handling of backpressure and errors.
 
 ```js
 const { once } = require('events');

doc/releases.md

@@ -540,7 +540,7 @@ formatting passes the lint rules on `master`.
 
 ### 13. Promote and Sign the Release Builds
 
-**It is important that the same individual who signed the release tag be the one
+**The same individual who signed the release tag must be the one
 to promote the builds as the SHASUMS256.txt file needs to be signed with the
 same GPG key!**
 

lib/_tls_common.js

@@ -100,8 +100,7 @@ exports.createSecureContext = function createSecureContext(options) {
   var i;
   var val;
 
-  // NOTE: It's important to add CA before the cert to be able to load
+  // Add CA before the cert to be able to load cert's issuer in C++ code.
-  // cert's issuer in C++ code.
   const { ca } = options;
   if (ca) {
     if (Array.isArray(ca)) {
@@ -132,7 +131,7 @@ exports.createSecureContext = function createSecureContext(options) {
     }
   }
 
-  // NOTE: It is important to set the key after the cert.
+  // Set the key after the cert.
   // `ssl_set_pkey` returns `0` when the key does not match the cert, but
   // `ssl_set_cert` returns `1` and nullifies the key in the SSL structure
   // which leads to the crash later on.

test/js-native-api/8_passing_wrapped/myobject.cc

@@ -51,10 +51,9 @@ napi_value MyObject::New(napi_env env, napi_callback_info info) {
 
   obj->env_ = env;
 
-  // It is important that the below call to napi_wrap() be such that we request
+  // The below call to napi_wrap() must request a reference to the wrapped
-  // a reference to the wrapped object via the out-parameter, because this
+  // object via the out-parameter, because this ensures that we test the code
-  // ensures that we test the code path that deals with a reference that is
+  // path that deals with a reference that is destroyed from its own finalizer.
-  // destroyed from its own finalizer.
   NAPI_CALL(env, napi_wrap(env,
                           _this,
                           obj,

test/parallel/test-url-parse-format.js

@@ -892,9 +892,8 @@ const parseTests = {
     href: 'https:///*'
   },
 
-  // The following two URLs are the same, but they differ for
+  // The following two URLs are the same, but they differ for a capital A.
-  // a capital A: it is important that we verify that the protocol
+  // Verify that the protocol is checked in a case-insensitive manner.
-  // is checked in a case-insensitive manner.
   'javascript:alert(1);a=\x27@white-listed.com\x27': {
     protocol: 'javascript:',
     slashes: null,