Improve readme

@ralphtheninja @juliangruber

Following https://github.com/Level/levelup/pull/455#discussion_r135388839, here’s a list of possible improvements as well as related issues. We can address these with multiple PRs or break it up into issues. I thought it best to first get an overview, and to start a discussion on the general goals:

• Consistent wording
• Reduce focus on LevelDOWN and LevelDB, make it generic
• Express a preference for using *down layers (like encoding-down) to extend functionality
• Drop documentation that can be found elsewhere.
• Recommend level

Notes per section

• Introduction
  • Rewrite. Possibly merge with Relationship to LevelDOWN. Sentences like “LevelDOWN is now optional because LevelUP can be used with alternative backends” are not wrong but I’d prefer opening with “LevelUP can be used with multiple backends” and thén saying “most commonly that’s LevelDOWN”.
  • Remove “LevelUP will look for LevelDOWN and throw an error if it can’t find it in its Node require() path. It will also tell you if the installed version of LevelDOWN is incompatible.”. No longer true.
  • Level should be the preferred way of using levelup + encoding-down + leveldown
  • I feel it’s important we keep the description of characteristics (e.g. lexicographical order), but maybe it can be explained not through a description of LevelDB, but by saying "backends follow the characteristics of LevelDB: <list of characteristics>.
• Tested & supported platforms:
  • Remove (backend-specific) list of platforms
  • But perhaps do mention we support both Node.js and browser
  • Improve LevelDOWN’s documentation: Level/leveldown#380
• Basic usage
  • No longer true: “All operations are asynchronous although they don’t necessarily require a callback if you don’t need to know when the operation was performed.”
• db.createReadStream([options])
  • Drop this sentence: “The standard pause(), resume() and destroy() methods are implemented on the ReadStream, as is pipe() (see below). ‘data’, ‘error’, ‘end’ and ‘close’ events are emitted.” Linking to Node.js documentation should suffice.
• Extending LevelUP
  • “When attempting to extend the functionality of LevelUP, it is recommended that you consider using level-hooks and/or level-sublevel.”: I would personally recommend subleveldown and similar *down layers now. Alternatively we could remove this text and just link to the wiki.

General

• Pick one of “database” / “store” / “database store” / “underlying store” / “database backend” / “LevelDB store”: #502
• After the introduction, generalize or remove references to LevelDB, assuming the introduction has made it clear that a “store” (or whatever word we settle on) is abstract. E.g. “opening the underlying store with LevelDB” => “opening the store”.
• “Node.js-style readable stream”: drop the -style suffix? Seems to suggest it’s like a Node.js stream, but not actually.
• “records” / “entries” => “entries”
• “key/value pairs” => “key-value pairs”
• “data store” => “store”
• LevelUP => levelup, LevelDOWN => leveldown
• “can be arbitrary data objects” => “can be of any type”?
• Unquote 'key', 'value', 'gte', etc
• Add minimum Node.js version (https://github.com/Level/levelup/pull/469)
• Better explain encodings Moved to Level/encoding-down#15
• Link to a changelog: #444

[vweevers]

@ralphtheninja @juliangruber how do you feel about unquoting 'key', 'value', 'gte', etc? Make it easier to read. At least all the things that are properties of an object, where we don’t need to explain that they’re strings. E.g. key, value, gte.

[vweevers]

Added to the list above:

• “records” / “entries” => “entries”
• “key/value pairs” => “key-value pairs”
• “data store” => “store”
• “can be arbitrary data objects” => “can be of any type”?