Add readme to the docs directory

CONTRIBUTING.md

@@ -12,9 +12,12 @@ If you end up not being able to complete the task, please post another comment s
 Issues are also welcome, [failing tests](#writing-tests) are even more welcome.
 
 # Contribution Guidelines
- - Try to use feature branches rather than developing on master
- - Please include tests covering the change
- - The docs are now stored in the repository under the `Docs` folder, please include documentation updates with your PR
+ - Try to use feature branches rather than developing on master.
+ - Please include tests covering the change.
+ - The documentation is stored in the repository under the [`docs`](docs) folder.
+   Have a look at the [documentation readme file](docs/readme.md) for guidance
+   on how to improve the documentation and please include documentation updates
+   with your PR.
 
 # How it works
 See [how it works](http://gitversion.readthedocs.org/en/latest/more-info/how-it-works/) in GitVersion's documentation

docs/readme.md

@@ -0,0 +1,40 @@
+# GitVersion Documentation
+
+This is the directory in which the
+[GitVersion documentation hosted on ReadTheDocs](http://gitversion.readthedocs.io/en/latest/)
+resides.
+
+## Contributing
+
+Improvements to the documentation is highly welcomed and is as easy
+as finding the `.md` file you want to change and editing it directly within
+GitHub's web interface.
+
+If you want to do more elaborate changes, we would appreciate if you could test
+the documentation locally before submitting a pull request. This involves
+[forking](https://guides.github.com/activities/forking/) this repository and
+then serving up the documentation locally on your machine, clicking around in
+it to ensure that everything works as expected.
+
+## Serving the documentation locally
+
+To serve up the documentation locally, you need to
+[install MkDocs](http://www.mkdocs.org/#installation) and then at the root of
+the GitVersion project write the following in a command line window:
+
+```shell
+mkdocs serve
+```
+
+After pressing enter, something similar to the following lines should appear:
+
+```
+INFO    -  Building documentation...
+INFO    -  Cleaning site directory
+[I 160810 10:48:18 server:281] Serving on http://127.0.0.1:8000
+```
+
+If it says `Serving on http://127.0.0.1:8000`, you should be able to navigate
+your favorite browser to `http://127.0.0.1:8000` and browse the documentation
+there. If you have any problems with this process, please consult the
+[MkDocs documentation](http://www.mkdocs.org/).

src/GitVersionCore.Tests/DocumentationTests.cs

@@ -78,8 +78,12 @@ public void DocumentationIndexIsUpToDate()
                 .ToString()
                 .Replace("docs/", string.Empty);
 
-            Console.WriteLine(fullPath);
-            Console.WriteLine(relativePath);
+            // The readme file in the docs directory is not supposed to be deployed to ReadTheDocs;
+            // it's only there for the convenience of contributors wanting to improve the documentation itself.
+            if (relativePath == "readme.md")
+            {
+                continue;
+            }
 
             documentationIndexFile.ShouldContain(relativePath, () => string.Format("The file '{0}' is not listed in 'mkdocs.yml'.", relativePath));
         }