Add frequently asked questions / issues to top of readme

Author: James McKinney

README.rst

@@ -26,7 +26,21 @@ csvkit is a suite of command-line tools for converting to and working with CSV,
 
 It is inspired by pdftk, GDAL and the original csvcut tool by Joe Germuska and Aaron Bycoffe.
 
-If you need to do more complex data analysis than csvkit can handle, use `agate <https://github.com/wireservice/agate>`_.
+.. note::
+
+    If you need to do more complex data analysis than csvkit can handle, use `agate <https://github.com/wireservice/agate>`_.
+
+.. note::
+
+    Remember that to change the field separator, line terminator, etc. of the **output**, you must use :doc:`/scripts/csvformat`.
+
+.. note::
+
+    csvkit, by default, `sniffs <https://docs.python.org/3.5/library/csv.html#csv.Sniffer>`_ CSV formats (it deduces whether commas, tabs or spaces delimit fields, for example), and performs type inference (it converts text to numbers, dates, booleans, etc.). These features are useful and work well in most cases, but occasional errors occur. If you don't need these features, set :code:`--snifflimit 0` (:code:`-y 0`) and :code:`--no-inference` (:code:`-I`).
+
+.. note::
+
+    If you need csvkit to be faster or to handle larger files, you may be reaching the limits of csvkit.
 
 Important links:
 

docs/tricks.rst

@@ -52,6 +52,12 @@ csvkit is supported on:
 
 It is tested on macOS, and has also been used on Linux and Windows.
 
+If installing on macOS, you may need to install Homebrew first::
+
+    /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
+    brew install python
+    pip install csvkit
+
 If installing on Ubuntu, you may need to install Python's development headers first::
 
     sudo apt-get install python-dev python-pip python-setuptools build-essential
@@ -101,7 +107,7 @@ For some data, type inference can be error prone. If necessary you can disable i
 Slow performance
 ----------------
 
-csvkit's tools fall into two categories: Those that load an entire CSV into memory (e.g. :doc:`/scripts/csvstat`) and those that only read data one row at a time (e.g. :doc:`/scripts/csvcut`). Those that stream results will generally be very fast. For those that buffer the entire file, the slowest part of that process is typically the "type inference" described in the previous section.
+csvkit's tools fall into two categories: Those that load an entire CSV into memory (e.g. :doc:`/scripts/csvstat`) and those that only read data one row at a time (e.g. :doc:`/scripts/csvcut`). Those that stream results will generally be very fast. See :doc:`contributing` for a full list. For those that buffer the entire file, the slowest part of that process is typically the "type inference" described in the previous section.
 
 If a tool is too slow to be practical for your data try setting the :code:`--snifflimit` option or using the :code:`--no-inference`.