Hopefully explain better what vdirs are

docs/vdir.rst

@@ -5,6 +5,11 @@ The Vdir Storage Format
 This document describes a standard for storing calendars and contacts on a
 filesystem, with the main goal of being easy to implement.
 
+Vdirsyncer synchronizes to vdirs via
+:py:class:`vdirsyncer.storage.filesystem.FilesystemStorage`. Each vdir
+(basically just a directory with some files in it) represents a calendar or
+addressbook.
+
 Basic Structure
 ===============
 

docs/when.rst

@@ -7,9 +7,9 @@ When do I need Vdirsyncer?
 Why not Dropbox? (or anything like it)
 ======================================
 
-Since vdirs are just a bunch of files, it is obvious to try *file
-synchronization* for synchronizing your data between multiple computers, such
-as:
+Since :doc:`vdirs <vdir>` are just a bunch of files, it is obvious to try
+*file synchronization* for synchronizing your data between multiple computers,
+such as:
 
 * `Syncthing <https://syncthing.net/>`_
 * `Dropbox <https://dropbox.com/>`_ or one of the gajillion services like it

vdirsyncer/storage/singlefile.py

@@ -37,8 +37,9 @@ class SingleFileStorage(Storage):
 
     .. note::
         This storage is very slow, and that is unlikely to change. You should
-        consider using :py:class:`vdirsyncer.storage.FilesystemStorage` if it
-        fits your usecase.
+        consider using
+        :py:class:`vdirsyncer.storage.filesystem.FilesystemStorage` if it fits
+        your usecase.
 
     :param path: The filepath to the file to be written to.
     :param encoding: Which encoding the file should use. Defaults to UTF-8.