Improve Landing Page and Quickstart Guide

README.rst

@@ -3,7 +3,7 @@ blueapi
 
 |code_ci| |docs_ci| |coverage| |pypi_version| |license|
 
-Lightweight Bluesky-as-a-service wrapper application. Also usable as a library. 
+Lightweight bluesky-as-a-service wrapper application. Also usable as a library. 
 
 ============== ==============================================================
 PyPI           ``pip install blueapi``
@@ -12,7 +12,28 @@ Documentation  https://DiamondLightSource.github.io/blueapi
 Releases       https://github.com/DiamondLightSource/blueapi/releases
 ============== ==============================================================
 
-TODO: Talk about automagic plan endpoints
+This module wraps bluesky_ plans and devices inside a server and exposes endpoints to send commands/receive data.
+Useful for installation at labs where multiple people may control equipment, 
+possibly from remote locations.
+
+|concept|
+
+The main premise of blueapi is to minimize the boilerplate required to get plans
+and devices up and running by generating an API for your lab out of type-annotated 
+plans. For example, take the following plan:
+
+.. code:: python
+
+    import bluesky.plans as bp
+    from blueapi.core import MsgGenerator
+
+    def my_plan(foo: str, bar: int) -> MsgGenerator:
+        yield from bp.scan(...)
+
+Blueapi's job is to detect this plan and automatically add it to the lab's API so it
+can be invoked easily with a few REST calls. 
+
+.. _bluesky: https://blueskyproject.io/bluesky
 
 .. |code_ci| image:: https://github.com/DiamondLightSource/blueapi/actions/workflows/code.yml/badge.svg?branch=main
     :target: https://github.com/DiamondLightSource/blueapi/actions/workflows/code.yml
@@ -38,4 +59,8 @@ TODO: Talk about automagic plan endpoints
     Anything below this line is used when viewing README.rst and will be replaced
     when included in index.rst
 
+
+.. |concept| image:: docs/images/blueapi.png
+    :width: 800px
+
 See https://DiamondLightSource.github.io/blueapi for more detailed documentation.

docs/index.rst

@@ -3,6 +3,9 @@
 .. include:: ../README.rst
     :end-before: when included in index.rst
 
+.. |concept| image:: images/blueapi.png
+    :width: 800px
+
 How the documentation is structured
 -----------------------------------
 

docs/user/tutorials/quickstart.rst

@@ -3,6 +3,10 @@ Quickstart Guide
 
 .. seealso:: Assumes you have completed `./installation`.
 
+Blueapi acts as a worker that can run bluesky plans against devices for a specific
+laboratory setup. It can control devices to collect data and export events to tell
+downstream services about the data it has collected.
+
 
 Start ActiveMQ
 --------------
@@ -42,4 +46,15 @@ The worker can also be started using a custom config file:
     blueapi --config path/to/file serve
 
 
+Test that the Worker is Running
+-------------------------------
+
+Blueapi comes with a CLI so that you can query and control the worker from the terminal.
+
+.. code:: shell
+
+    blueapi controller plans
+
+The above command should display all plans the worker is capable of running.
+
 .. seealso:: Full CLI reference: `../reference/cli`