wip

README.md

@@ -1,10 +1,34 @@
 # [Sqids Go](https://sqids.org/go)
 
+[![GoDoc](https://godoc.org/github.com/sqids/sqids-go?status.svg)](https://godoc.org/github.com/sqids/sqids-go)
 [![Github Actions](https://img.shields.io/github/actions/workflow/status/sqids/sqids-go/tests.yml)](https://github.com/sqids/sqids-go/actions)
 
-Sqids (pronounced "squids") is a small library that lets you generate YouTube-looking IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.
+[Sqids](https://sqids.org/go) (*pronounced "squids"*) is a small library that lets you **generate unique IDs from numbers**. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.
 
-## Getting started
+Features:
+
+- **Encode multiple numbers** - generate short IDs from one or several non-negative numbers
+- **Quick decoding** - easily decode IDs back into numbers
+- **Unique IDs** - generate unique IDs by shuffling the alphabet once
+- **ID padding** - provide minimum length to make IDs more uniform
+- **URL safe** - auto-generated IDs do not contain common profanity
+- **Randomized output** - Sequential input provides nonconsecutive IDs
+- **Many implementations** - Support for [40+ programming languages](https://sqids.org/)
+
+## 🧰 Use-cases
+
+Good for:
+
+- Generating IDs for public URLs (eg: link shortening)
+- Generating IDs for internal systems (eg: event tracking)
+- Decoding for quicker database lookups (eg: by primary keys)
+
+Not good for:
+
+- Sensitive data (this is not an encryption library)
+- User IDs (can be decoded revealing user count)
+
+## 🚀 Getting started
 
 Use go get.
 
@@ -18,7 +42,7 @@ Then import the package into your own code.
 import "github.com/sqids/sqids-go"
 ```
 
-## Examples
+## 👩‍💻 Examples
 
 > 🚧 Please note that the following examples omit proper error handling:
 
@@ -30,6 +54,9 @@ id, _ := s.Encode([]uint64{1, 2, 3}) // "8QRLaD"
 numbers := s.Decode(id) // [1, 2, 3]
 ```
 
+> **Note**
+> 🚧 Because of the algorithm's design, **multiple IDs can decode back into the same sequence of numbers**. If it's important to your design that IDs are canonical, you have to manually re-encode decoded numbers and check that the generated ID matches.
+
 Randomize IDs by providing a custom alphabet:
 
 ```golang
@@ -62,6 +89,6 @@ id, _ := s.Encode([]uint64{1, 2, 3}) // "8QRLaD"
 numbers := s.Decode(id) // [1, 2, 3]
 ```
 
-## License
+## 📝 License
 
 [MIT](LICENSE)