diff --git a/doc/.eslintrc.yaml b/doc/.eslintrc.yaml
index b81bec6508..b4fbf847be 100644
--- a/doc/.eslintrc.yaml
+++ b/doc/.eslintrc.yaml
@@ -1,5 +1,12 @@
+## Docs-specific linter rules
+
 rules:
-  strict: 0
+  # ease some restrictions in doc examples
   no-restricted-properties: 0
   no-undef: 0
   no-unused-vars: 0
+  strict: 0
+
+  # add new ECMAScript features gradually
+  no-var: 2
+  prefer-const: 2
diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index 58fdad2a3d..c2f6740c87 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -20,7 +20,7 @@ server.on('message', (msg, rinfo) => {
 });
 
 server.on('listening', () => {
-  var address = server.address();
+  const address = server.address();
   console.log(`server listening ${address.address}:${address.port}`);
 });
 
@@ -146,7 +146,7 @@ server.on('message', (msg, rinfo) => {
 });
 
 server.on('listening', () => {
-  var address = server.address();
+  const address = server.address();
   console.log(`server listening ${address.address}:${address.port}`);
 });
 
diff --git a/doc/api/stream.md b/doc/api/stream.md
index c8462760f5..b750dd49b1 100644
--- a/doc/api/stream.md
+++ b/doc/api/stream.md
@@ -237,7 +237,7 @@ function writeOneMillionTimes(writer, data, encoding, callback) {
   let i = 1000000;
   write();
   function write() {
-    var ok = true;
+    let ok = true;
     do {
       i--;
       if (i === 0) {
@@ -869,7 +869,7 @@ the internal buffer is fully drained.
 ```js
 const readable = getReadableStreamSomehow();
 readable.on('readable', () => {
-  var chunk;
+  let chunk;
   while (null !== (chunk = readable.read())) {
     console.log(`Received ${chunk.length} bytes of data.`);
   }
@@ -1004,14 +1004,14 @@ function parseHeader(stream, callback) {
   stream.on('error', callback);
   stream.on('readable', onReadable);
   const decoder = new StringDecoder('utf8');
-  var header = '';
+  let header = '';
   function onReadable() {
-    var chunk;
+    let chunk;
     while (null !== (chunk = stream.read())) {
-      var str = decoder.write(chunk);
+      const str = decoder.write(chunk);
       if (str.match(/\n\n/)) {
         // found the header boundary
-        var split = str.split(/\n\n/);
+        const split = str.split(/\n\n/);
         header += split.shift();
         const remaining = split.join('\n\n');
         const buf = Buffer.from(remaining, 'utf8');
@@ -1598,12 +1598,12 @@ class Counter extends Readable {
   }
 
   _read() {
-    var i = this._index++;
+    const i = this._index++;
     if (i > this._max)
       this.push(null);
     else {
-      var str = '' + i;
-      var buf = Buffer.from(str, 'ascii');
+      const str = '' + i;
+      const buf = Buffer.from(str, 'ascii');
       this.push(buf);
     }
   }
diff --git a/doc/api/util.md b/doc/api/util.md
index 612439bbea..af3cceb332 100644
--- a/doc/api/util.md
+++ b/doc/api/util.md
@@ -59,7 +59,7 @@ it is marked as deprecated.
 const util = require('util');
 
 exports.puts = util.deprecate(function() {
-  for (var i = 0, len = arguments.length; i < len; ++i) {
+  for (let i = 0, len = arguments.length; i < len; ++i) {
     process.stdout.write(arguments[i] + '\n');
   }
 }, 'util.puts: Use console.log instead');
diff --git a/doc/api/vm.md b/doc/api/vm.md
index 60bde1d729..aaf53b73c4 100644
--- a/doc/api/vm.md
+++ b/doc/api/vm.md
@@ -116,7 +116,7 @@ const sandbox = {
 const script = new vm.Script('count += 1; name = "kitty";');
 
 const context = new vm.createContext(sandbox);
-for (var i = 0; i < 10; ++i) {
+for (let i = 0; i < 10; ++i) {
   script.runInContext(context);
 }
 
@@ -203,7 +203,7 @@ global.globalVar = 0;
 
 const script = new vm.Script('globalVar += 1', { filename: 'myfile.vm' });
 
-for (var i = 0; i < 1000; ++i) {
+for (let i = 0; i < 1000; ++i) {
   script.runInThisContext();
 }
 
@@ -231,14 +231,14 @@ will remain unchanged.
 const util = require('util');
 const vm = require('vm');
 
-var globalVar = 3;
+global.globalVar = 3;
 
 const sandbox = { globalVar: 1 };
 vm.createContext(sandbox);
 
 vm.runInContext('globalVar *= 2;', sandbox);
 
-console.log(util.inspect(sandbox)); // 2
+console.log(util.inspect(sandbox)); // { globalVar: 2 }
 
 console.log(util.inspect(globalVar)); // 3
 ```
@@ -296,7 +296,7 @@ const vm = require('vm');
 const sandbox = { globalVar: 1 };
 vm.createContext(sandbox);
 
-for (var i = 0; i < 10; ++i) {
+for (let i = 0; i < 10; ++i) {
   vm.runInContext('globalVar *= 2;', sandbox);
 }
 console.log(util.inspect(sandbox));
@@ -399,9 +399,10 @@ local scope, but does have access to the current `global` object.
 The following example illustrates using both `vm.runInThisContext()` and
 the JavaScript [`eval()`][] function to run the same code:
 
+<!-- eslint-disable prefer-const -->
 ```js
 const vm = require('vm');
-var localVar = 'initial value';
+let localVar = 'initial value';
 
 const vmResult = vm.runInThisContext('localVar = "vm";');
 console.log('vmResult:', vmResult);
diff --git a/doc/api/zlib.md b/doc/api/zlib.md
index 340470a4e1..c422719a01 100644
--- a/doc/api/zlib.md
+++ b/doc/api/zlib.md
@@ -69,7 +69,7 @@ const request = http.get({ host: 'example.com',
                            port: 80,
                            headers: { 'Accept-Encoding': 'gzip,deflate' } });
 request.on('response', (response) => {
-  var output = fs.createWriteStream('example.com_index.html');
+  const output = fs.createWriteStream('example.com_index.html');
 
   switch (response.headers['content-encoding']) {
     // or, just use zlib.createUnzip() to handle both cases
@@ -94,8 +94,8 @@ const zlib = require('zlib');
 const http = require('http');
 const fs = require('fs');
 http.createServer((request, response) => {
-  var raw = fs.createReadStream('index.html');
-  var acceptEncoding = request.headers['accept-encoding'];
+  const raw = fs.createReadStream('index.html');
+  let acceptEncoding = request.headers['accept-encoding'];
   if (!acceptEncoding) {
     acceptEncoding = '';
   }
diff --git a/doc/guides/using-internal-errors.md b/doc/guides/using-internal-errors.md
index 948a87612e..16b8c90963 100644
--- a/doc/guides/using-internal-errors.md
+++ b/doc/guides/using-internal-errors.md
@@ -27,7 +27,7 @@ are intended to replace existing `Error` objects within the Node.js source.
 For instance, an existing `Error` such as:
 
 ```js
-  var err = new TypeError('Expected string received ' + type);
+  const err = new TypeError('Expected string received ' + type);
 ```
 
 Can be replaced by first adding a new error key into the `internal/errors.js`
@@ -42,7 +42,7 @@ Then replacing the existing `new TypeError` in the code:
 ```js
   const errors = require('internal/errors');
   // ...
-  var err = new errors.TypeError('FOO', type);
+  const err = new errors.TypeError('FOO', type);
 ```
 
 ## Adding new errors
@@ -80,8 +80,8 @@ codes.
 ```js
 const errors = require('internal/errors');
 
-var arg1 = 'foo';
-var arg2 = 'bar';
+const arg1 = 'foo';
+const arg2 = 'bar';
 const myError = new errors.Error('KEY', arg1, arg2);
 throw myError;
 ```
@@ -100,8 +100,8 @@ The `myError` object will have a `code` property equal to the `key` and a
 ```js
 const errors = require('internal/errors');
 
-var arg1 = 'foo';
-var arg2 = 'bar';
+const arg1 = 'foo';
+const arg2 = 'bar';
 const myError = new errors.TypeError('KEY', arg1, arg2);
 throw myError;
 ```
@@ -120,8 +120,8 @@ The `myError` object will have a `code` property equal to the `key` and a
 ```js
 const errors = require('internal/errors');
 
-var arg1 = 'foo';
-var arg2 = 'bar';
+const arg1 = 'foo';
+const arg2 = 'bar';
 const myError = new errors.RangeError('KEY', arg1, arg2);
 throw myError;
 ```
diff --git a/doc/guides/writing-tests.md b/doc/guides/writing-tests.md
index 70690e2fda..3cb87623ae 100644
--- a/doc/guides/writing-tests.md
+++ b/doc/guides/writing-tests.md
@@ -141,22 +141,22 @@ this with a real test from the test suite.
 
 ```javascript
 'use strict';
-var common = require('../common');
-var assert = require('assert');
-var http = require('http');
+require('../common');
+const assert = require('assert');
+const http = require('http');
 
-var request = 0;
-var response = 0;
+let request = 0;
+let response = 0;
 process.on('exit', function() {
   assert.equal(request, 1, 'http server "request" callback was not called');
   assert.equal(response, 1, 'http request "response" callback was not called');
 });
 
-var server = http.createServer(function(req, res) {
+const server = http.createServer(function(req, res) {
   request++;
   res.end();
 }).listen(0, function() {
-  var options = {
+  const options = {
     agent: null,
     port: this.address().port
   };
@@ -172,14 +172,13 @@ This test could be greatly simplified by using `common.mustCall` like this:
 
 ```javascript
 'use strict';
-var common = require('../common');
-var assert = require('assert');
-var http = require('http');
+const common = require('../common');
+const http = require('http');
 
-var server = http.createServer(common.mustCall(function(req, res) {
+const server = http.createServer(common.mustCall(function(req, res) {
   res.end();
 })).listen(0, function() {
-  var options = {
+  const options = {
     agent: null,
     port: this.address().port
   };