Camelot is a big place with a lot of problems, but there's one we care about. In this first paragraph, you must explain what that problem is. Our problem is that Camelot needs a leader.
Camelot needs a solution, and excalibur is the (clever -- maybe even cheeky) name of the one thing that solves this one problem best. It sounds almost magical in how it could simply solve the problems above - problems that many people have tried to solve before. Now, you explain how it solves those problems: excalibur tells you instantly whether or not a person is that leader.
In this final introductory paragraph, you explain how excalibur works differently than most other attempted solutions. Specifically, it's hard to pull out of a stone, so only real leaders can do it.
$ pip install excalibur
When in doubt, make installation a single line.
excalibur consists of a single function, but your magical and awesome package may consist of more. #Here's where you briefly describe what each function does.# can_become_king accepts a single Django user, and returns a bool. What's more, this method makes sense: it tells you what it'll return, and it tells you what it needs. It doesn't matter that excalibur is a sword. What the sword does matters far more.
excalibur = Excalibur()
arthur = User.objects.get(first_name="Arthur")
excalibur.can_become_king(arthur)
> True
- be too technical. Focus on the pain of the users.
- be too brief. You need to do more than tell people how to use it. You have to tell them why they should.
- be too broad. It would be great if everyone used your open source project. But it's better to focus on a clear, small case where this solution is the best. First, find people who care more than anyone else. Second, make them care even more.