Update readme

Author: shian15810

README.md

@@ -1,3 +1,79 @@
 # eslint-plugin-typescript-enum
 
 ESLint rules for TypeScript enums.
+
+## Motivations
+
+From [TypeScript Handbook on Enums](https://www.typescriptlang.org/docs/handbook/enums.html):
+
+> Enums are one of the few features TypeScript has which is not a type-level extension of JavaScript.
+
+In other words, TypeScript enums have their corresponsing runtime representations, they are not erased from your emitted JavaScript files after being compiled. This conflicts with one of the non-goals of [TypeScript Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals):
+
+> Provide additional runtime functionality or libraries. Instead, use TypeScript to describe existing libraries.
+
+Having this TypeScript feature extending into your compiled JavaScript also conflicts with the TypeScript slogan of being a **typed superset of JavaScript**, which further introduces vendor lock-in.
+
+[Orta Therox](https://github.com/orta) from Typescript team mentioned in [one of his YouTube video](https://youtu.be/8qm49TyMUPI?t=1240) that the TypeScript team actually regrets some of the changes it made in the beginning, including introducing enums which basically add features to JavaScript.
+
+Moreover, using enums in TypeScript has a lot of caveats and edge cases to keep in mind. Some aspects of it are even considered not **type safe**!!! Head over to these wonderful articles for more details on these issues:
+
+- https://maxheiber.medium.com/alternatives-to-typescript-enums-50e4c16600b1
+- https://stackoverflow.com/questions/40275832/typescript-has-unions-so-are-enums-redundant/60041791#60041791
+
+Additionally, if you have been using [@babel/plugin-transform-typescript](https://babeljs.io/docs/en/babel-plugin-transform-typescript.html), you might already know that one of the caveats is to avoid using `const enum`s, as those require type information to compile.
+
+Nonetheless, TypeScript is still a very fantastic and powerful programming language that I love very much. Enums may have been a very good feature to have back in the early days (2011) when good alternatives did not yet exist.
+
+However, we now already have alternatives better than enums, such as **const assertions** and **string unions**. Which is why I created this ESLint plugin to provide you with some configs and rules to disallow the use of TypeScript enums.
+
+This article provides a very in-depth exploration on the alternatives to TypeScript enums: https://2ality.com/2020/02/enum-alternatives-typescript.html
+
+## Installation
+
+First, install the required peer dependencies:
+
+```sh
+npm install --save-dev eslint typescript @typescript-eslint/parser
+```
+
+Next, install this package:
+
+```sh
+npm install --save-dev eslint-plugin-typescript-enum
+```
+
+## Usage
+
+### Recommended Config
+
+Configure this plugin in your ESLint configuration file (`.eslintrc.js`), this will disallow the use of enums altogether:
+
+```js
+module.exports = {
+  parser: "@typescript-eslint/parser",
+  plugins: ["typescript-enum"],
+  extends: ["typescript-enum/recommended"],
+};
+```
+
+### Babel Config (Not Recommended)
+
+For those that using [@babel/plugin-transform-typescript](https://babeljs.io/docs/en/babel-plugin-transform-typescript.html) and you want to allow the use of enums except `const enum`:
+
+```js
+module.exports = {
+  parser: "@typescript-eslint/parser",
+  plugins: ["typescript-enum"],
+  extends: ["typescript-enum/babel"],
+};
+```
+
+## Rules
+
+**Key**: :heavy_check_mark: = recommended, :wrench: = fixable, :thought_balloon: = requires type information
+
+| Name                                                             | Description                     | :heavy_check_mark: | :wrench: | :thought_balloon: |
+| ---------------------------------------------------------------- | ------------------------------- | ------------------ | -------- | ----------------- |
+| [`typescript-enum/no-const-enum`](./docs/rules/no-const-enum.md) | Disallow the use of const enums |                    |          |                   |
+| [`typescript-enum/no-enum`](./docs/rules/no-enum.md)             | Disallow the use of enums       | :heavy_check_mark: |          |                   |

docs/rules/no-const-enum.md

@@ -1,6 +1,6 @@
-# Disallow the use of TypeScript const enums (`no-const-enum`)
+# Disallow the use of const enums (`no-const-enum`)
 
-This rule disallows the use of TypeScript const enums.
+This rule disallows the use of `const enum`s.
 
 ## Rule Details
 

docs/rules/no-enum.md

@@ -1,6 +1,6 @@
-# Disallow the use of TypeScript enums (`no-enum`)
+# Disallow the use of enums (`no-enum`)
 
-This rule disallows the use of TypeScript enums.
+This rule disallows the use of enums.
 
 ## Rule Details