added docs

Author: ajinkya-k

docs/src/constructors.md

@@ -1,7 +1,7 @@
 # Model constructors
 
 The `LinearMixedModel` type represents a linear mixed-effects model.
-Typically it is constructed from a `Formula` and an appropriate `Table` type, usually a `DataFrame`.
+Typically, it is constructed from a `Formula` and an appropriate `Table` type, usually a `DataFrame`.
 
 ## Examples of linear mixed-effects model fits
 
@@ -58,6 +58,15 @@ fm1 = fit(MixedModel, fm, dyestuff)
 DisplayAs.Text(ans) # hide
 ```
 
+You can also use the convenience function `lmm` to fit the model as follows:
+
+```@example Main
+fm = @formula(yield ~ 1 + (1|batch))
+fm2 = lmm(fm, dyestuff)
+DisplayAs.Text(ans) # hide
+```
+Notice that both are equivalent.
+
 (If you are new to Julia you may find that this first fit takes an unexpectedly long time, due to Just-In-Time (JIT) compilation of the code. The subsequent calls to such functions are much faster.)
 
 ```@example Main
@@ -210,14 +219,18 @@ DisplayAs.Text(ans) # hide
 ## Fitting generalized linear mixed models
 
 To create a GLMM representation, the distribution family for the response, and possibly the link function, must be specified.
+You can either use `fit(MixedModel, ...)` or `glmm(...)` to fit the model. For instance:
 
 ```@example Main
 verbagg = MixedModels.dataset(:verbagg)
 verbaggform = @formula(r2 ~ 1 + anger + gender + btype + situ + mode + (1|subj) + (1|item));
 gm1 = fit(MixedModel, verbaggform, verbagg, Bernoulli())
 DisplayAs.Text(ans) # hide
 ```
-
+The model can also be fit as
+```@example Main
+gm1 = glmm(verbaggform, verbagg, Bernoulli())
+```
 The canonical link, which is `LogitLink` for the `Bernoulli` distribution, is used if no explicit link is specified.
 
 Note that, in keeping with convention in the [`GLM` package](https://github.com/JuliaStats/GLM.jl), the distribution family for a binary (i.e. 0/1) response is the `Bernoulli` distribution.

docs/src/index.md

@@ -7,6 +7,33 @@ CurrentModule = MixedModels
 *MixedModels.jl* is a Julia package providing capabilities for fitting and examining linear and generalized linear mixed-effect models.
 It is similar in scope to the [*lme4*](https://github.com/lme4/lme4) package for `R`.
 
+# TLDR
+
+```@setup Main
+using DisplayAs
+```
+You can fit a model using a `lmer`-style model formula using `@formula` and a dataset.
+Here is a short example of how to fit a linear mixed-effects modeling using the `dyestuff` dataset:
+
+```@example Main
+using DataFrames, MixedModels           # load packages
+dyestuff = MixedModels.dataset(:dyestuff);              # load dataset
+
+lmod = lmm(@formula(yield ~ 1 + (1|batch)), dyestuff)   # fit the model!
+DisplayAs.Text(ans) # hide
+```
+For a generalized linear mixed-effect model, you have to specify a distribution for the response variable (and optionally a link function).
+A quick example of generalized linear model using the `verbagg` dataset:
+
+```@example Main
+using DataFrames, MixedModels               # load packages
+verbagg = MixedModels.dataset(:verbagg);    # load dataset
+
+frm = @formula(r2 ~ 1 + anger + gender + btype + situ + mode + (1|subj) + (1|item));
+bernmod = glmm(frm, verbagg, Bernoulli())   # fit the model!
+DisplayAs.Text(ans) # hide
+```
+
 ```@contents
 Pages = [
         "constructors.md",