Improve docs and deprecation about prettyPrint (pinojs#1203)

docs/api.md

@@ -358,7 +358,8 @@ and searching for logged objects can start from a consistent path.
 
 Default: `false`
 
-__DEPRECATED: use [`transport`](#transport) instead.__
+__DEPRECATED: look at [pino-pretty documentation](https://github.com/pinojs/pino-pretty)
+for alternatives__. Using a [`transport`](#transport) is also an option.__
 
 Enables pretty printing log logs. This is intended for non-production
 configurations. This may be set to a configuration object as outlined in the

examples/basic.js

@@ -1,7 +1,14 @@
 'use strict'
 
+// Pino's primary usage writes ndjson to `stdout`:
 const pino = require('..')()
 
+// However, if "human readable" output is desired,
+// `pino-pretty` can be provided as the destination
+// stream by uncommenting the following line in place
+// of the previous declaration:
+// const pino = require('..')(require('pino-pretty')())
+
 pino.info('hello world')
 pino.error('this is at error level')
 pino.info('the answer is %d', 42)

lib/deprecations.js

@@ -5,4 +5,4 @@ module.exports = warning
 
 const warnName = 'PinoWarning'
 
-warning.create(warnName, 'PINODEP008', 'prettyPrint is deprecated, use the pino-pretty transport instead')
+warning.create(warnName, 'PINODEP008', 'prettyPrint is deprecated, look at https://github.com/pinojs/pino-pretty for alternatives.')