appium/appium — pull request #1287 by filmaj (2013-10-08 23:54:00+00:00)
Title: README review

My first experience with Appium was difficult. I found myself jumping between the README and the website and the wiki (and then the docs/ folder once I discovered it) and searching for answers which were not answered in the README. Even just understanding that Appium is a middle-man between test code and a mobile device was not obvious to me when I started!

This pull request is a long-running attempt at fixing many of these problems. I tried to consolidate a lot of the existing information in the README into cohesive sections. I tried answering some of the questions that originally I did not have answers for when I started with Appium.

I dropped some "__TODO__" items in the README that I'd like to get people's opinions on.

If anyone has any other ideas or "good to have"'s - please comment!

My ultimate objective would be try to reduce the readme down to a single page or two. It is about 270 lines right now. If we can distill it down to about 200 lines, that'd be ideal, IMO.

The README is the very first impression anyone who wants to play with the project has. When I look up a new project, I am interested in, in order of importance:

1. Why do I want to use the project, what does it give me?
2. What do I need to have to run the project? (i.e. requirements)
3. How can I make sure it works really quickly? (i.e. a legit quick-start, ours is too long right now)
4. How do I run the project's tests to make sure I didn't break anything?
5. What are the guidelines for contributing?

I think the first four points need a little work, but this pull request is a start. As for #5, perhaps it makes more sense to move stuff to a `CONTRIBUTING.md` document?

I'd like for this pull request not to be merged until we are satisfied that most of the above points were addressed.

Fire away!