search

ssadler / hawk

Awk for Hoodlums
BSD 3-Clause "New" or "Revised" License
35 stars 2 forks source link

Improve README #18

Open gelisam opened 11 years ago

gelisam commented 11 years ago

This is the first thing the user will see when he hears of our project, and will determine whether the user closes the tab, stars the project, or installs it.

I think a good landing page must quickly and convincingly expose the product's main selling point. Only one. For my experimental branch, that point was the type-inference magic. What is hawk's main selling point?

I think the very best thing would have been a showterm video, but since we can't embed it in the readme, I think we should list our most important examples, then link to a showterm video with more.

I think installation instructions need to be the last thing on the page, once the user is already convinced.

melrief commented 11 years ago

Maybe we should start using the github wiki

gelisam commented 11 years ago

For discussions, or do you think we should populate it with useful material for the users? Personally, as a user, I have never viewed the wiki of any project, in fact I didn't even know that github had wikis.

melrief commented 11 years ago

I remember this stackoverflow question about embedding videos in readme.md. Apparently you can't but you can do it into a github.io page.

The readme is limited, it should expose just the essential informations. Wiki support different pages and content can be organized. For instance, the library Hspec has this page and hsp has (this)[http://melrief.github.io/HSProcess/].

gelisam commented 11 years ago

If our video is short, an animated gif of a terminal interaction might do the trick!

melrief commented 11 years ago

Ok, that black magic could do it :D. Fine for me!