Add a philosophy section (#73)

Also expand the example class a little bit to stress that we're not just
about data containers.

README.rst

@@ -33,9 +33,14 @@ For that, it gives you a class decorator and a way to declaratively define the a
    ... class C(object):
    ...     x = attr.ib(default=42)
    ...     y = attr.ib(default=attr.Factory(list))
+   ...
+   ...     def hard_math(self, z):
+   ...         return self.x * self.y * z
    >>> i = C(x=1, y=2)
    >>> i
    C(x=1, y=2)
+   >>> i.hard_math(3)
+   6
    >>> i == C(1, 2)
    True
    >>> i != C(2, 1)

docs/api.rst

@@ -105,6 +105,8 @@ Core
 .. autoexception:: attr.exceptions.FrozenInstanceError
 
 
+.. _helpers:
+
 Helpers
 -------
 

docs/overview.rst

@@ -9,6 +9,39 @@ In order to fullfil its ambitious goal of bringing back the joy to writing class
    :end-before: -testimonials-
 
 
+.. _philosophy:
+
+Philosophy
+==========
+
+It's about regular classes.
+   ``attrs`` for creating well-behaved classes with a type, attributes, methods, and everything that comes with a class.
+   It can be used for data-only containers like ``namedtuple``\ s or ``types.SimpleNamespace`` but they're just a sub-genre of what ``attrs`` is good for.
+
+The class belongs to the users.
+   You define a class and ``attrs`` adds static methods to that class based on the attributes you declare.
+   The end.
+   It doesn't add meta classes.
+   It doesn't add classes you've never heard of to your inheritance tree.
+   An ``attrs`` class in runtime is indistiguishable from a regular class: because it *is* a regular class with a few boilerplate-y methods attached.
+
+Be light on API impact.
+   As convenient as it seems at first, ``attrs`` will *not* tack on any methods to your classes save the dunder ones.
+   Hence all the useful :ref:`tools <helpers>` that come with ``attrs`` live in functions that operate on top of instances.
+   Since they take an ``attrs`` instance as their first argument, you can attach them to your classes with one line of code.
+
+Performance matters.
+   ``attrs`` runtime impact is very close to zero because all the work is done when the class is defined.
+   Once you're instantiating it, ``attrs`` is out of the picture completely.
+
+No surprises.
+   ``attrs`` creates classes that arguably work the way a Python beginner would reasonably expect them to work.
+   It doesn't try to guess what you mean because explicit is better than implicit.
+   It doesn't try to be clever because software shouldn't be clever.
+
+Check out :doc:`how-does-it-work` if you'd like to know how it achieves all of the above.
+
+
 What ``attrs`` Is Not
 =====================