Add example file

README.org

@@ -7,3 +7,36 @@ DocSpec is
 2. a Common Lisp library to query the file
 3. a command line client built on the library
 4. an Emacs package, providing a =completing-read= interface
+
+It is hoped that providing such a tool will not only make life easier for users of (DocSpec-using) projects, but also make more projects aware of the [[https://diataxis.fr/][Diataxis Framework]], helping them make their documentation easier to read and maintain.
+
+* Creating the file
+Below is what an example DocSpec file for the [[https://github.com/McCLIM/McCLIM/][McCLIM]] project might look like.
+
+Each documentation type has topics it covers - in this example, each topic is a symbol, but they could also be strings.
+
+The documentation for each topic can be presented in one or more formats - a string, a PDF file, an HTML file, etc.
+
+#+BEGIN_SRC lisp
+((tutorial
+  (first-attempt     (:pdf "<url>") (:html "<url>"))
+  (defining-commands (:pdf "<url>") (:html "<url>"))
+  ...)
+ (howto
+  (create-text-editor-pane    (:pdf "<url>") (:html "<url>"))
+  (run-app-in-separate-thread (:pdf "<url>") (:html "<url>"))
+  (create-new-backend         (:pdf "<url>") (:html "<url>"))
+  ...)
+ (explanation
+  (coordinate-systems  (:pdf "<url>") (:html "<url>"))
+  (sheet-hierarchies   (:pdf "<url>") (:html "<url>"))
+  (development-history (:pdf "<url>") (:html "<url>"))
+  ...)
+ (reference
+  (redisplay       (:pdf "<url>") (:html "<url>"))
+  (layout-protocol (:pdf "<url>") (:html "<url>"))
+  (output-protocol (:pdf "<url>") (:html "<url>"))
+  ...))
+#+END_SRC
+
+Tools making use of DocSpec can offer commands such as =view-tutorial=, =view-howto=, =view-explanation=, and =view-reference=. Users can configure a priority list for their preferred formats; if the package does not offer documentation in any of those formats, the tool could prompt them to select an available format.