Added some very simple docs to detail usage of API

Author: JamieMair

docs/make.jl

@@ -10,7 +10,8 @@ makedocs(
                 "Backends"     =>  "custom_behaviour.md",
                 "Reading back data" => "deserialization.md",
                 "Extending"    =>  "extending_behaviour.md",
-                "Explicit Interface" => "explicit_interface.md"
+                "Explicit Interface" => "explicit_interface.md",
+                "Hyperparameter API" => "hyperparameter_api.md"
             ],
             "Examples"      => Any[
                 "Flux.jl"  => "examples/flux.md"

docs/src/examples/hyperparameter_tuning.md

@@ -0,0 +1,53 @@
+# Hyperparameter Tuning
+
+We will start this example by setting up a simple random walk experiment, and seeing the effect of the hyperparameter `bias` on the results.
+
+First, import the packages we will need with:
+```julia
+using TensorBoardLogger, Logging
+using Random
+```
+Next, we will create a function which runs the experiment and logs the results, include the hyperparameters stored in the `config` dictionary.
+```julia
+function run_experiment(id, config)
+    logger = TBLogger("random_walk/run$id", tb_append)
+
+    # Specify all the metrics we want to track in a list
+    metric_names = ["scalar/position"]
+    write_hparams!(logger, config, metric_names)
+
+    epochs = config["epochs"]
+    sigma = config["sigma"]
+    bias = config["bias"]
+    with_logger(logger) do
+        x = 0.0
+        for i in 1:epochs
+            x += sigma * randn() + bias
+            @info "scalar" position = x
+        end
+    end
+    nothing
+end
+```
+Now we can write a script which runs an experiment over a set of parameter values.
+```julia
+id = 0
+for bias in LinRange(-0.1, 0.1, 11)
+    for epochs in [50, 100]
+        config = Dict(
+            "bias"=>bias,
+            "epochs"=>epochs,
+            "sigma"=>0.1
+        )
+        run_experiment(id, config)
+        id += 1
+    end
+end
+```
+
+Below is an example of the dashboard you get when you open Tensorboard with the command:
+```sh
+tensorboard --logdir=random_walk
+```
+
+![tuning plot](tuning.png)

docs/src/examples/tuning.png

@@ -0,0 +1,12 @@
+# Hyperparameter Experiments
+
+In additition to logging the experiments, you may wish to also visualise the effect of hyperparameters on some plotted metrics. This can be done by logging the hyperparameters via the `write_hparams!` function, which takes a dictionary mapping hyperparameter names to their values (currently limited to `Real`, `Bool` or `String` types), along with the names of any metrics that you want to view the effects of. 
+
+You can see how the HParams dashboard in Tensorboard can be used to tune hyperparameters on the [tensorboard website](https://www.tensorflow.org/tensorboard/hyperparameter_tuning_with_hparams).
+
+![hparams dashboard view](https://www.tensorflow.org/tensorboard/images/hparams_parallel_coordinates.png?raw=1)
+
+## HParams API
+```@docs
+write_hparams!
+```

docs/src/hyperparameter_api.md

@@ -117,6 +117,9 @@ We also support logging custom types from a the following third-party libraries:
 
 ## Explicit logging
 
-In alternative, you can also log data to TensorBoard through its functional interface,
-by calling the relevant method with a tag string and the data. For information
-on this interface refer to [Explicit interface](@ref)...
+As an alternative, you can also log data to TensorBoard through its functional interface, by calling the relevant method with a tag string and the data. For information on this interface refer to [Explicit interface](@ref).
+
+## Hyperparameter tuning
+
+Many experiments rely on hyperparameters, which can be difficult to tune. Tensorboard allows you to visualise the effect of your hyperparameters on your metrics, giving you an intuition for the correct hyperparameters for your task. For information on this API, see the [Hyperparameter API](@ref).
+