wip documentation (faq and about sections)

Author: benbovy

doc/about.rst

@@ -3,27 +3,55 @@
 About xarray-simlab
 ===================
 
+xarray-simlab provides a framework for easily building custom models from a set
+of re-usable components (i.e., Python classes), called processes.
 
+The framework handles issues that scientists who develop models should not care
+too much about, like a model interface and its data structure as well as its
+overall workflow management. Both are automatically determined from the
+succint, declarative-like interfaces of the model processes.
+
+Next versions of xarray-simlab will hopefully also handle other technical issues
+like logging, command line integration and running (many) simulations in
+parallel.
 
 Motivation
 ----------
+xarray-simlab is being developped with the idea of reducing the gap between the
+environment used for building and running a computational model and the one(s)
+used for processing and analysing simulation results. It also encourages
+building new models from re-usable components and avoid reinventing the wheel.
 
-The project is being developped with the idea of
+Ultimately, it should reduce the time lag between the ideas that scientists have
+on how to model a particular phenomenon and the insights they get from exploring
+the behavior of the model, which often itself lead to new modeling ideas.
 
 Sources of inspiration
 ----------------------
 
-xarray: data structure
-dask: task graphs (DAGs)
-luigi: use classes as primary, re-usable units for chaining many tasks
-django: especially The Django's ORM part (i.e., django.db.models) for the
-design of Process and Variable classes
-param: another source of inspiration for Process interface and Variable objects.
-climlab: another python package for process-oriented modeling, applied to
-climate
-
-
-(put this in create models section)
+- xarray_: data structure
+- dask_: build and run task graphs (DAGs)
+- luigi_: use Python classes as re-usable units that help building complex
+  workflows.
+- django_: especially The Django's ORM part (i.e., django.db.models) for the
+  design of Process and Variable classes
+- param_: another source of inspiration for Process interface and Variable objects.
+- climlab_: another python package for process-oriented modeling, applied to
+  climate.
+
+.. _xarray: https://github.com/pydata/xarray
+.. _dask: https://github.com/dask/dask
+.. _luigi: https://github.com/spotify/luigi
+.. _django: https://github.com/django/django
+.. _param: https://github.com/ioam/param
+.. _climlab: https://github.com/brian-rose/climlab
+
+**Draft: put this in create models section**
+
+The framework consists of a few base classes, e.g., :py:class:`xrsimlab.Variable`,
+:py:class:`xrsimlab.Process` and :py:class:`xrsimlab.Model`. The latter class
+represents a model with which we interact using the xarray's
+:py:class:`xarray.Dataset` structure.
 
 Variable.state (or value, rate, change) should not be used (get/set) outside
 of Process subclasses.

doc/faq.rst

@@ -6,14 +6,31 @@ Frequently Asked Questions
 Does xarray-simlab provide built-in models?
 -------------------------------------------
 
-No.
+No, xarray-simlab provides only the framework for creating, customizing and
+running computational models. It is intended to be a general-purpose tool.
+Domain specific models should be implemented in 3rd party packages. For example,
+`xarray-topo`_ provides xarray-simlab models and model components for simulating
+landscape evolution.
+
+.. _`xarray-topo`: https://gitext.gfz-potsdam.de/sec55-public/xarray-topo
 
 Will xarray-simlab support Python 2.7.x?
 ----------------------------------------
 
-No, unless there are very good reasons to do so.
+No, unless there are very good reasons to do so. The main packages of the Python
+scientific ecosystem support Python 3.4 or later, and it seems that Python 2.x
+will not be maintained anymore past 2020 (see `PEP 373`_). Although some tools
+easily allow supporting both Python 2 and 3 versions in a single code base,
+it still makes the code harder to maintain.
+
+.. _`PEP 373`: https://www.python.org/dev/peps/pep-0373/
+
 
 Which features are likely to be implemented in next xarray-simlab releases?
 ---------------------------------------------------------------------------
 
-(put here a link to the roadmap).
+Some ideas for future development can be found in the roadmap_ on the
+xarray-simlab's Github wiki_.
+
+.. _roadmap: https://github.com/benbovy/xarray-simlab/wiki/Roadmap
+.. _wiki: https://github.com/benbovy/xarray-simlab/wiki

doc/index.rst

@@ -46,7 +46,7 @@ Documentation Index
 Get in touch
 ------------
 
-- Report bugs, suggest features or view the source code `on GitHub`_.
+- You can report bugs, suggest features or view the source code `on GitHub`_.
 
 .. _on GitHub: http://github.com/benbovy/xarray-simlab