From e013745f1cd2b3d5c613a90ddf31962e86b3dda0 Mon Sep 17 00:00:00 2001
From: Adrian Sampson <adrian@radbox.org>
Date: Sat, 17 Sep 2011 16:02:06 -0700
Subject: [PATCH] introductory paragraphs

---
 docs/guides/index.rst    |  6 ++++--
 docs/guides/main.rst     |  5 ++++-
 docs/index.rst           | 19 ++++++++++++++++++-
 docs/reference/cli.rst   |  8 +++++++-
 docs/reference/index.rst |  4 +++-
 5 files changed, 36 insertions(+), 6 deletions(-)

diff --git a/docs/guides/index.rst b/docs/guides/index.rst
index 4d03b9b79..0544e2b55 100644
--- a/docs/guides/index.rst
+++ b/docs/guides/index.rst
@@ -1,10 +1,12 @@
 Guides
 ======
 
-Tutorial stuff
+This section contains a couple of walkthroughs that will help you get familiar
+with beets. If you're new to beets, you'll want to begin with the :doc:`main`
+guide.
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
    main
    tagger
diff --git a/docs/guides/main.rst b/docs/guides/main.rst
index 28ec70a9d..2304f01b2 100644
--- a/docs/guides/main.rst
+++ b/docs/guides/main.rst
@@ -1,7 +1,10 @@
 Getting Started
 ===============
 
-TODO Intro Text
+Welcome to `beets`_! This guide will help you begin using it to make your music
+collection better.
+
+.. _beets: http://beets.radbox.org/
 
 Installing
 ----------
diff --git a/docs/index.rst b/docs/index.rst
index 0c7de5497..be38e4201 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -1,7 +1,24 @@
 beets: the music geek's media organizer
 =======================================
 
-Intro text.
+Welcome to the documentation for `beets`_, the media library management system
+for obsessive-compulsive music geeks.
+
+If you're new to beets, begin with the :doc:`guides/main` guide. That guide
+walks you through installing beets, setting it up how you like it, and starting
+to build your music library.
+
+Then you can get a more detailed look at beets' features in the
+:doc:`/reference/cli/` and :doc:`/reference/config` references. You might also
+be interested in exploring the :ref:`included-plugins`.
+
+If you still need help, your can drop by the ``#beets`` IRC channel on Freenode,
+`email the author`_, or `file a bug`_ in the issue tracker. Please let me know
+where you think this documentation can be improved.
+
+.. _beets: http://beets.radbox.org/
+.. _email the author: mailto:adrian@radbox.org
+.. _file a bug: http://code.google.com/p/beets/issues/entry
 
 Contents
 --------
diff --git a/docs/reference/cli.rst b/docs/reference/cli.rst
index cb8b297e1..b02ce2aa1 100644
--- a/docs/reference/cli.rst
+++ b/docs/reference/cli.rst
@@ -3,7 +3,13 @@ Command-Line Interface
 
 **beet** is the command-line interface to beets.
 
-TODO: global flags
+You invoke beets by specifying a *command*, like so::
+
+    beet COMMAND [ARGS...]
+
+The rest of this document describes the available commands. If you ever need a
+quick list of what's available, just type ``beet help`` or ``beet help COMMAND``
+or help with a specific command.
 
 import
 ------
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
index 216f70c51..42600dc93 100644
--- a/docs/reference/index.rst
+++ b/docs/reference/index.rst
@@ -1,7 +1,9 @@
 Reference
 =========
 
-This section contains reference materials for various parts of beets.
+This section contains reference materials for various parts of beets. To get
+started with beets as a new user, though, you may want to read the
+:doc:`/guides/main` guide first.
 
 .. toctree::
    :maxdepth: 2