Merge pull request #154 from 3ptscience/feat/readme_update

Update readme with improved why/scope and more fleshed out alternatives

README.rst

@@ -39,23 +39,26 @@ An overview of Properties, November 2016.
 Why
 ---
 
-Giving structure (and documentation!) to the properties you use in your
-classes avoids confusion and allows users to interact flexibly and provide
-multiple styles of input, have those inputs validated, and allow you as a
-developer to set expectations for what you want to work with.
+Properties provides structure to aid development in an interactive programming
+environment while allowing for an easy transition to production code.
+It emphasizes usability and reproducibility for developers and users at
+every stage of the code life cycle.
 
 Scope
 -----
 
-The :code:`properties` package allows you to create **strongly typed** objects in a
-consistent way. This allows you to hook into **notifications** and other libraries.
+The :code:`properties` package enables the creation of **strongly typed** objects in a
+consistent, declarative way. This allows **validation** of developer expectations and hooks
+into **notifications** and other libraries. It provides **documentation** with
+no extra work, and **serialization** for portability and reproducibility.
 
 Goals
 -----
 
-* Keep a clean name space so that it can be used easily by users
+* Keep a clean namespace for easy interactive programming
 * Prioritize documentation
-* Connect to other libraries for interactive visualizations
+* Provide built-in serialization/deserialization
+* Connect to other libraries for GUIs and visualizations
 
 Documentation
 -------------
@@ -65,14 +68,51 @@ API Documentation is available at `ReadTheDocs <https://propertiespy.readthedocs
 Alternatives
 ------------
 
-* `traits <https://github.com/enthought/traits>`_ is used by Enthought
-* `traitlets <https://github.com/ipython/traitlets>`_ is used in the Jupyter project
-* `mypy <https://github.com/python/mypy>`_ and `PEP0484 <https://www.python.org/dev/peps/pep-0484/>`_ which document typing but do not include coercion or notifications
+* `traitlets <https://github.com/ipython/traitlets>`_ (Jupyter project) and
+  `traits <https://github.com/enthought/traits>`_ (Enthought) - These libraries
+  are driven by GUI development (much of the Jupyter environment is built
+  on traitlets; traits has automatic GUI generation) which leads to many
+  similar features to properties (strong typing, validation, and notifications).
+  However, There are a few key areas where properties differs:
+
+    1. properties has a clean namespace - this (in addition to `?` docstrings)
+       allows for very easy discovery in an interactive programming environment.
+    2. properties prioritizes documentation - this is not explicitly implemented
+       yet in traits or traitlets, but works out-of-the-box in properties.
+    3. properties prioritizes serialization - this is present in traits with
+       pickling (but difficult to customize) and in traitlets with configuration
+       files (which require extra work beyond standard class definition); in
+       properties, serialization works out of the box but is also highly
+       customizable.
+    4. properties allows invalid object states - the GUI focus of traits/traitlets
+       means an invalid object state at any time is never ok; without that constraint,
+       properties allows interactive object building and experimentation.
+       Validation then occurs when the user is ready and calls :code:`validate`
+
+  Significant advantages of traitlets and traits over properties are
+  GUI interaction and the much larger suite of existing property types.
+
+* `param <https://github.com/ioam/param>`_ - This library also provides
+  type-checking, validation, and notification. It has a few unique features
+  and parameter types (possibly of note is the ability to provide dynamic
+  values for parameters at any time, not just as the default). This was first
+  introduced before builtin Python properties, and current development is
+  very slow.
+
+* `mypy <https://github.com/python/mypy>`_ and `PEP0484 <https://www.python.org/dev/peps/pep-0484/>`_ -
+  This provides static typing for Python without coersion, notifications, etc.
+  It has a very different scope and implementation than traits-like libraries.
+
+* `builtin Python property <https://docs.python.org/3/library/functions.html#property>`_ -
+  properties/traits-like behavior can be mostly recreated using :code:`@property`.
+  This requires significantly more work by the programmer, and results in
+  not-declarative, difficult-to-read code.
 
 Connections
 -----------
 
 * `SimPEG <https://github.com/simpeg/simpeg>`_ Simulation and Parameter Estimation in Geophysics
+* `Steno3D <https://github.com/3ptscience/steno3dpy>`_ Python client for building and uploading 3D models
 
 Installation
 ------------