diff --git a/docs/Makefile b/docs/Makefile
index 1f646c7..b725a42 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -1,34 +1,44 @@
-SHELL := /bin/bash
+default: serve
 
-default: book
+GENERATED_DOCS = build_glossary.md
 
-build: swagger
-	ln -s ../platform-install/docs platform-install && \
-	ln -s ../../test/cord-tester/docs test && \
-	ln -s ../../orchestration/xos/docs xos && \
-	ln -s ../../orchestration/xos-gui/docs xos-gui && \
-	ln -s ../../orchestration/xos-tosca/docs xos-tosca && \
-	ln -s ../../orchestration/profiles profiles && \
-	gitbook install && gitbook build
-
-book: clean build
+serve: setup
 	gitbook serve
-clean:
-	rm -rf _book; \
-	rm -rf node_modules; \
-	rm platform-install; \
-	rm test; \
-	rm profiles; \
-	rm xos; \
-	rm xos-gui; \
-	rm xos-tosca; \
-	rm -f ../platform-install/docs/docs; \
-	rm -f ../../test/cord-tester/docs/docs; \
-	rm -f ../../orchestration/xos/docs/docs; \
-	rm -f ../../orchestration/xos-gui/docs/docs; \
-	rm -f ../../orchestration/xos-tosca/docs/docs; \
-	rm -f ../../orchestration/profiles/profiles
 
-swagger:
+build: setup
+	gitbook build
+
+setup: clean platform-install test profiles xos xos-gui xos-tosca swagger $(GENERATED_DOCS)
+	gitbook init
+	gitbook install
+
+platform-install:
+	ln -s ../platform-install/docs platform-install
+
+test:
+	ln -s ../../test/cord-tester/docs test
+
+profiles:
+	ln -s ../../orchestration/profiles profiles
+
+xos:
+	ln -s ../../orchestration/xos/docs xos
+
+xos-gui:
+	ln -s ../../orchestration/xos-gui/docs xos-gui
+
+xos-tosca:
+	ln -s ../../orchestration/xos-tosca/docs xos-tosca
+
+build_glossary.md: scripts/descriptions.md scripts/defaults.md.j2 scripts/defaultsdoc.py scripts/markedyaml.py
+	python scripts/defaultsdoc.py -o build_glossary.md
+
+swagger: xos
 	pushd ../../orchestration/xos/docs/; make swagger_docs; popd;
 
+clean:
+	rm -rf $(GENERATED_DOCS)
+	rm -rf _book
+	rm -rf node_modules
+	rm -f platform-install test profiles xos xos-gui xos-tosca
+