bring the FAQ into the docs fold

mahmoud · Jun 25, 2016 · 3d77057 · 3d77057
1 parent 2103854
commit 3d77057
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 5 deletions.
diff --git a/docs/faq.rst b/docs/faq.rst
@@ -1,8 +1,9 @@
 Frequently Asked Questions
 ==========================
 
-Lithoxyl's many powerful paradigms mean that there is plenty to
-learn. Here are a few of the questions that pop up more than others.
+Lithoxyl's new approach answers quite a lot of questions, but raises a
+few others. These questions fall into two categories, `Design
+<#design-questions>`_ and `Background <#background-questions>`_.
 
 Design questions
 ----------------
@@ -55,10 +56,11 @@ If you discover a runtime scenario that should degrade with more grace
 or a configuration-time scenario which could prevent runtime failures
 through more forward checking, please do file an issue.
 
-Factual questions
------------------
+Background questions
+--------------------
 
-Other questions are pretty straightforward.
+Unlike the design questions above, background questions relate to just
+the objective facts.
 
 .. ref:: etymology
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -21,4 +21,5 @@ Sections
    sinks
    sensible
    logging_tradition
+   faq
    glossary