update index of documentation add documentation documentation (yo)

diff --git a/pdns/docs/markdown/appendix/documentation.md b/pdns/docs/markdown/appendix/documentation.md
new file mode 100644 (file)
index 0000000..14668f8
--- /dev/null
+++ b/pdns/docs/markdown/appendix/documentation.md
@@ -0,0 +1,21 @@
+# Documentation details
+The PowerDNS documentation started life as SGML DocBook, and was later converted (with great pain) to XML DocBook. Late 2014, 
+Pieter Lexis contributed a Markdown conversion, which is the basis of the current documentation.
+
+If you note an issue with the new documentation, please open a ticket on
+https://github.com/powerdns/pdns/issues and tell us about it. Or, even
+better, fork our repo, and edit the files in
+https://github.com/PowerDNS/pdns/tree/master/pdns/docs/markdown to improve
+things.
+
+If your change is simple (say, a typo or a new paragraph), you can do all this 
+entirely from GitHub. Simply fork PowerDNS, find the Markdown file you want to change, 
+edit in place, commit, and create a fork request. 
+
+To test-build the documentation, run ''pip install mkdocs'', ''pip install
+pandoc'' and ''pip install pandocfilters'', followed by ''make
+html-new/index.html'' in the pdns/docs directory.
+
+To test your changes live, use ''mkdocs serve --dev-addr=0.0.0.0:8000'', and the new version
+of your documentation will appear on port 8000 of your machine.
+

diff --git a/pdns/docs/markdown/index.md b/pdns/docs/markdown/index.md
index 89c8e570d573f1748f12f79971ad11ad19909d56..803ea2ab3d423035060f8c38c57c0cd07d855437 100644 (file)
--- a/pdns/docs/markdown/index.md
+++ b/pdns/docs/markdown/index.md
@@ -1,19 +1,27 @@
 # PowerDNS Nameserver
 
-PowerDNS (PDNS) consists of two parts: the [Authoritative Server](authoritative/index.md) and the [Recursor](recursor/index.md). While most other nameservers fully combine these functions, PowerDNS offers them separately, but can mix both authoritative and recursive usage seamlessly.
+There are two PowerDNS nameserver products:the [Authoritative Server](authoritative/index.md) and the [Recursor](recursor/index.md). While most other nameservers fully combine these functions, PowerDNS offers them separately, but can mix both authoritative and recursive usage seamlessly.
 The Authoritative Server will answer questions about domains it knows about, but will not go out on the net to resolve queries about other domains. However, it can use a recursing backend to provide that functionality. Depending on your needs, this backend can either be the PowerDNS recursor or an external one.
 When the Authoritative Server answers a question, it comes out of the database, and can be trusted as being authoritative. There is no way to pollute the cache or to confuse the daemon.
 
 The Recursor, conversely, by default has no knowledge of domains itself, but will always consult other authoritative servers to answer questions given to it.
 
-PDNS has been designed to serve both the needs of small installations by being easy to setup, as well as for serving very large query volumes on large numbers of domains. Additionally, through use of clever programming techniques, PowerDNS offers very high domain resolution performance.
+PowerDNS has been designed to serve both the needs of small installations by
+being easy to setup, as well as for serving very large query volumes on
+large numbers of domains.  Additionally, through use of clever programming
+techniques, PowerDNS offers very high domain resolution performance.
 
-Another prime goal is security. By the use of language features, the PDNS source code is reasonably small which makes auditing easy. In the same way, library features have been used to mitigate the risks of buffer overflows.
+Another prime goal is security. By the use of language features, the PowerDNS
+source code is reasonably small which makes auditing easy.  In the same way,
+library features have been used to mitigate the risks of buffer overflows.
 
-Finally, PowerDNS is able to give a lot of statistics on its operation which is both helpful in determining the scalability of an installation as well as for spotting problems.
+Finally, PowerDNS is able to give a lot of statistics on its operation which
+is both helpful in determining the scalability of an installation as well as
+for spotting problems.
 
 # About this document
 If you are reading this document from disk, you may want to check <http://doc.powerdns.com> for updates.
+To add to the PowerDNS documentation, or to fix mistakes, head to [Documentation details](appendix/documentation.md).
 
 > It is a book about a Spanish guy called Manual. You should read it.  
 

diff --git a/pdns/docs/mkdocs.yml b/pdns/docs/mkdocs.yml
index 30548d340515b12092f2a88c367962299c74dc37..2d6f69825aa763f6a4150432e65f9f7ebc063643 100644 (file)
--- a/pdns/docs/mkdocs.yml
+++ b/pdns/docs/mkdocs.yml
@@ -61,5 +61,6 @@ pages:
   - [security/powerdns-advisory-2006-02.md, 'Security', 'Advisory 2006-02']
   - [security/powerdns-advisory-2006-01.md, 'Security', 'Advisory 2006-01']
   - [appendix/backend-writers-guide.md, 'Tools and Appendices', "Backend Writer's Guide"]
+  - [appendix/documentation.md, 'Tools and Appendices', "Documentation detauls"]
   - [appendix/compiling-powerdns.md, 'Tools and Appendices', 'Compiling PowerDNS']
   - [tools/analysis.md, 'Tools and Appendices', 'DNS Analysis Tools']