What is an awesome list?

Search GitHub for almost any technical subject and you will find a repository called awesome-something: awesome-python, awesome-selfhosted, awesome-security, awesome-kubernetes. These are awesome lists: curated collections of links on one topic, kept in a README file and maintained like software, with issues, pull requests and reviewers. The convention started in 2014 when Sindre Sorhus created sindresorhus/awesome, an index of such lists, and wrote down guidelines for what a list should look like. That index now points to hundreds of lists and is one of the most starred repositories on GitHub.

What makes a list "awesome"

The guidelines matter more than the name. A list that follows them has a few recognisable properties:

• Curated, not collected. The maintainers include only things they consider genuinely good, and say no to pull requests that merely add more. A list that accepts everything is a search result, not a recommendation.
• One line per entry. Each link has a short description that tells you what it is before you click.
• Organised by section. Entries are grouped so you can find the area you care about without reading everything.
• Open to contribution. There is a contributing guide, and changes arrive through reviewed pull requests, so you can see who added what and why.
• No self-promotion as the main purpose. Good lists link to the thing itself, not to a blog post about it.

How to judge whether a list is maintained

Lists go stale because links rot and projects die. Before you rely on one, spend a minute on the repository page:

1. Look at the date of the last commit. A list on an active subject that has not changed in two years is probably abandoned, however many stars it has.
2. Open the pull requests tab. Many open, unreviewed pull requests from months ago mean nobody is at the wheel.
3. Check whether the list has a contributing guide and whether rejected pull requests get a reason. That shows curation is happening.
4. Click a handful of links in the section you need. If several are dead or point to archived projects, treat the whole list with suspicion.
5. See whether the list is in the sindresorhus/awesome index. Inclusion requires a review against the guidelines, which filters out the worst.

How to use lists without getting lost

An awesome list is a map, and the mistake people make is trying to visit every place on it. Use it with a question in mind: “which tools exist for X?” or “where do people learn Y?”. Go to the matching section, read the descriptions, and shortlist two or three entries. Then leave the list and evaluate those projects on their own merits: licence, last release, open issues, documentation. Stars are a weak signal of quality and a strong signal of age, so do not sort by them. If you find yourself opening twenty tabs, close the list and come back when you have a narrower question.

Because a list is one Markdown file, the fastest way to search it is to clone it and grep for a keyword rather than scrolling:

git clone --depth 1 https://github.com/sbilly/awesome-security.git
grep -i honeypot awesome-security/README.md

In the security field, awesome-security is the broadest general list and a good first stop; the entry in this topic describes how it is organised. From there you will find more specialised lists for areas such as incident response, threat intelligence, malware analysis and specific platforms. Each of those is maintained by different people, so apply the checks above to every list separately.

Official documentation

• The awesome index (sindresorhus/awesome)
• The awesome manifesto: what qualifies a list