tweaks

Author: ablaom

docs/src/anatomy_of_an_implementation.md

@@ -95,8 +95,10 @@ Regarding the return value of `fit`:
 Our `fit` method assumes that `X` is a table (satifies the [Tables.jl
 spec](https://github.com/JuliaData/Tables.jl)) whose rows are the observations; and it
 will need need `y` to be an `AbstractFloat` vector. A model implementation is free to
-dictate the representation of data that `fit` accepts but must articulate its requirements
-using appropriate traits; see [Training data types](@ref) below.
+dictate the representation of data that `fit` accepts but articulates its requirements
+using appropriate traits; see [Training data types](@ref) below. We recommend against data
+type checks internal to `fit`; this would ordinarily be the responsibility of a higher
+level API, using those trasits. 
 
 
 ## Operations

docs/src/index.md

@@ -13,7 +13,7 @@ A basic Julia interface for training and applying machine learning models </span
 - For developers wanting to **IMPLEMEMT** LearnAPI: [Anatomy of
   an Implementation](@ref).
 
-- For those who wanting to **USE** models implementing LearnAPI.jl: [Basic fit/predict
+- For those who wanting to **USE** models implementing LearnAPI: [Basic fit/predict
   workflow](@ref workflow).
 
 ## Approach
@@ -43,9 +43,10 @@ on the target proxy.
 
 ## Methods
 
-LearnAPI.jl is a base interface for machine learning algorithms in which behaviour is
-articulated using traits. It has no abstract model types, apart from an optional supertype
-`Model`. It provides the following methods, dispatched on model type:
+In LearnAPI.jl a *model* is just a container for the hyper-parameters of some machine
+learning algorithm, and that's all. It does not include learned parameters.
+
+The following methods, dispatched on model type, are provided:
 
 - `fit` for regular training, overloaded if the model generalizes to new data, as in
   classical supervised learning
@@ -94,7 +95,7 @@ resampling*. However, LearnAPI.jl is predicated on a few basic undefined notions
 
 - Each machine learning model's behaviour is governed by a number of user-specified
   **hyperparameters**. The regularization parameter in ridge regression is an
-  example. Hyperparameters are data independent. For example, the number of target classes
+  example. Hyperparameters are data-independent. For example, the number of target classes
   is not a hyperparameter.
 
 - Information needed for training that is not a model hyperparameter and not data is