diff --git a/docs/README.md b/docs/README.md
index 17c8437056..a183bdfa9a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,15 +7,16 @@ This site was built using the tomjohnson1492/documentation-theme-jekyll theme
A Jekyll-based theme designed for documentation and help systems. See the link for detailed instructions on setting up and configuring everything. http://idratherbewriting.com/documentation-theme-jekyll/
+## Building using Bundler
-Build the site to see the instructions for using it. Or just go here: [http://idratherbewriting.com/documentation-theme-jekyll/](http://idratherbewriting.com/documentation-theme-jekyll/)
-
-Run `bundle exec jekyll serve --watch` to fire up Jekyll on local machine
-
-## Using Docker
-
-One time: `docker build --no-cache -t mydocs .`
-
-Now run the site with `docker run --rm=true -v "$PWD:/src" -p 4005:4005 mydocs serve -H 0.0.0.0`
+ bundle install # once
+ bundle exec jekyll serve
+
+Go to: http://localhost:4005/
+
+## Building using Docker
+
+ docker build --no-cache -t pmd-doc . # once
+ docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
Go to: http://localhost:4005/
diff --git a/docs/_data/sidebars/pmd_sidebar.yml b/docs/_data/sidebars/pmd_sidebar.yml
index 775cabc9d9..81dfb2ea53 100644
--- a/docs/_data/sidebars/pmd_sidebar.yml
+++ b/docs/_data/sidebars/pmd_sidebar.yml
@@ -123,6 +123,9 @@ entries:
- title: Developer Resources
url: /pmd_devdocs_development.html
output: web, pdf
+ - title: Writing Documentation
+ url: /pmd_devdocs_writing_documentation.html
+ output: web, pdf
- title: Code Style
url: /pmd_devdocs_codestyle.html
output: web, pdf
diff --git a/docs/pages/pmd/devdocs/writing_documentation.md b/docs/pages/pmd/devdocs/writing_documentation.md
new file mode 100644
index 0000000000..d04e991bf1
--- /dev/null
+++ b/docs/pages/pmd/devdocs/writing_documentation.md
@@ -0,0 +1,140 @@
+---
+title: Writing Documentation
+last_update: August 2017
+permalink: pmd_devdocs_writing_documentation.html
+keywords: documentation, jekyll, markdown
+---
+
+PMD's documentation uses [Jekyll](https://jekyllrb.com/) with
+the [I'd rather be writing Jekyll Theme](http://idratherbewriting.com/documentation-theme-jekyll/index.html).
+
+Here are some quick tips.
+
+## Format
+
+The pages are in general in [Github Flavored Markdown](https://kramdown.gettalong.org/parser/gfm.html).
+
+## Structure
+
+All documentation is stored in the folder `docs/`. This is the folder, that github and the travis-ci scripts
+use to render the site.
+
+New pages are stored in the different subfolders under `pages`. The folder structure resembles the sidebar structure.
+Since all pages use a simple *permalink*, in the rendered html pages, all pages are flattened in one directory.
+This makes it easy to view the documentation also offline.
+
+## Building
+
+There are two ways, to execute jekyll:
+
+1. Using [bundler](http://bundler.io/). This will install all the needed ruby packages locally and execute jekyll:
+
+ # this is required only once, to download and install the dependencies
+ bundle install
+ # this builds the documentation under _site
+ bundle exec jekyll build
+ # this runs a local webserver as http://localhost:4005
+ bundle exec jekyll serve
+
+2. Using [docker](https://www.docker.com/). This will create a local docker image, into which all needed ruby
+ packages and jekyll is installed.
+
+ # this is required only once to create a local docker image named "pmd-doc"
+ docker build --no-cache -t pmd-doc .
+ # this builds the documentation under _site
+ docker run --rm=true -v "$PWD:/src" pmd-doc build -H 0.0.0.0
+ # this runs a local webserver as http://localhost:4005
+ docker run --rm=true -v "$PWD:/src" -p 4005:4005 pmd-doc serve -H 0.0.0.0
+
+The built site is stored locally in the (git ignored) directory `_site`. You can
+point your browser to `_site/index.html` to see the pmd documentation.
+
+Alternatively, you can start the local webserver, that will serve the documentation.
+Just go to http://localhost:4005.
+If a page is modified, the documentation will automatically be rendered again and
+all you need to do, is refreshing the page in your browser.
+
+
+## The sidebar
+
+The sidebar is stored as a YAML document under `_data/sidebars/pmd_sidebar.yml`.
+
+Make sure to add an entry there, whenever you create a new page.
+
+
+## The frontmatter
+
+Each page in jekyll begins with a YAML section at the beginning. This section
+is separated by 3 dashes (`---`). Example:
+
+ ---
+ title: Writing Documentation
+ last_update: August 2017
+ permalink: pmd_devdocs_writing_documentation.html
+ ---
+
+ Some Text
+
+ # Some header
+
+There are a couple of possible fields. Most important and always
+required are **title** and **permalink**.
+
+By default, a page **toc** (table of contents) is automatically generated.
+You can prevent this with "toc: false".
+
+You can add **keywords**, that will be used for the on-site search: "keywords: documentation, jekyll, markdown"
+
+It's useful to maintain a **last_update** field. This will be added at the bottom of the
+page.
+
+A **summary** can also be provided. It will be added in a box before the content.
+
+For a more exhaustive list, see [Pages - Frontmatter](http://idratherbewriting.com/documentation-theme-jekyll/mydoc_pages.html#frontmatter).
+
+
+## Alerts and Callouts
+
+See [Alerts](http://idratherbewriting.com/documentation-theme-jekyll/mydoc_alerts.html).
+
+For example, a info-box can be created like this:
+
+ {% include note.html content="This is a note." %}
+
+It renders as:
+
+{% include note.html content="This is a note." %}
+
+Other available types are:
+
+* note.html
+* tip.html
+* warning.html
+* important.html
+
+
+A callout is created like this:
+
+ {% include callout.html content="This is a callout of type default.
There are the following types available: danger, default, primary, success, info, and warning." type="default" %}
+
+It renders as:
+
+{% include callout.html content="This is a callout of type default.
There are the following types available: danger, default, primary, success, info, and warning." type="default" %}
+
+## Code samples with syntax highlighting
+
+This is as easy as:
+
+ ``` java
+ public class Foo {
+ public void bar() { System.out.println("x"); }
+ }
+ ```
+
+This looks as follows:
+
+``` java
+public class Foo {
+ public void bar() { System.out.println("x"); }
+}
+```