Some docs writing guidlines

readme

@@ -1,4 +1,30 @@
-This repository is for the RavenDB documenation
+This repository contains the official RavenDB documenation
 
-The compiled old book can be downloaded as a PDF from
-http://builds.hibernatingrhinos.com/download/2254
+The compiled old book can still be downloaded as a PDF from [http://builds.hibernatingrhinos.com/download/2254](http://builds.hibernatingrhinos.com/download/2254)
+
+The documentation is written using the [Markdown language](http://en.wikipedia.org/wiki/Markdown), and may use some extended Markdown features.
+
+* Images should be stored under a local "images" folder, right below the document referencing them. The reference should be to "images/image_name.png". Image names should bear a unique descriptive name, like clientapi_intro_serverimage.png.
+
+* Links to other documents within the documentation system should be relative, without the .markdown extension, e.g. href="../../server/deployment".
+
+The following non-standard syntax is supported as well:
+
+* For code blocks (supported: json, csharp):
+
+	{CODE-START:json /}
+	...
+	{CODE-END /}
+
+* For highlighted blocks:
+
+	{BLOCK ... /}
+	{NOTE ... /}
+	{INFO ... /}
+	{WARNING ... /}
+	{TIP ... /}
+	{WARNING ... /}
+
+* For a files list - will output a list of links to all child documents:
+
+	{FILES-LIST /}