diff --git a/docs/_config.yml b/docs/_config.yml
deleted file mode 100644
index 18854876c67..00000000000
--- a/docs/_config.yml
+++ /dev/null
@@ -1 +0,0 @@
-theme: jekyll-theme-midnight
\ No newline at end of file
diff --git a/hack/generator/spec/case-study-chained-storage-versions.md b/docs/design/case-study-chained-storage-versions.md
similarity index 100%
rename from hack/generator/spec/case-study-chained-storage-versions.md
rename to docs/design/case-study-chained-storage-versions.md
diff --git a/hack/generator/spec/case-study-fixed-storage-version.md b/docs/design/case-study-fixed-storage-version.md
similarity index 100%
rename from hack/generator/spec/case-study-fixed-storage-version.md
rename to docs/design/case-study-fixed-storage-version.md
diff --git a/hack/generator/spec/case-study-rolling-storage-versions.md b/docs/design/case-study-rolling-storage-versions.md
similarity index 100%
rename from hack/generator/spec/case-study-rolling-storage-versions.md
rename to docs/design/case-study-rolling-storage-versions.md
diff --git a/hack/generator/spec/crossplane.md b/docs/design/crossplane.md
similarity index 100%
rename from hack/generator/spec/crossplane.md
rename to docs/design/crossplane.md
diff --git a/hack/generator/spec/defaulter-validator.md b/docs/design/defaulter-validator.md
similarity index 100%
rename from hack/generator/spec/defaulter-validator.md
rename to docs/design/defaulter-validator.md
diff --git a/hack/generator/spec/images/case-study-chained-storage/2011-01-01.dot b/docs/design/images/case-study-chained-storage/2011-01-01.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2011-01-01.dot
rename to docs/design/images/case-study-chained-storage/2011-01-01.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2011-01-01.png b/docs/design/images/case-study-chained-storage/2011-01-01.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2011-01-01.png
rename to docs/design/images/case-study-chained-storage/2011-01-01.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2012-02-02.dot b/docs/design/images/case-study-chained-storage/2012-02-02.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2012-02-02.dot
rename to docs/design/images/case-study-chained-storage/2012-02-02.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2012-02-02.png b/docs/design/images/case-study-chained-storage/2012-02-02.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2012-02-02.png
rename to docs/design/images/case-study-chained-storage/2012-02-02.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2013-03-03.dot b/docs/design/images/case-study-chained-storage/2013-03-03.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2013-03-03.dot
rename to docs/design/images/case-study-chained-storage/2013-03-03.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2013-03-03.png b/docs/design/images/case-study-chained-storage/2013-03-03.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2013-03-03.png
rename to docs/design/images/case-study-chained-storage/2013-03-03.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2014-04-04-preview.dot b/docs/design/images/case-study-chained-storage/2014-04-04-preview.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2014-04-04-preview.dot
rename to docs/design/images/case-study-chained-storage/2014-04-04-preview.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2014-04-04-preview.png b/docs/design/images/case-study-chained-storage/2014-04-04-preview.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2014-04-04-preview.png
rename to docs/design/images/case-study-chained-storage/2014-04-04-preview.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2014-04-04.dot b/docs/design/images/case-study-chained-storage/2014-04-04.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2014-04-04.dot
rename to docs/design/images/case-study-chained-storage/2014-04-04.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2014-04-04.png b/docs/design/images/case-study-chained-storage/2014-04-04.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2014-04-04.png
rename to docs/design/images/case-study-chained-storage/2014-04-04.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2015-05-05-alternate.dot b/docs/design/images/case-study-chained-storage/2015-05-05-alternate.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2015-05-05-alternate.dot
rename to docs/design/images/case-study-chained-storage/2015-05-05-alternate.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2015-05-05-alternate.png b/docs/design/images/case-study-chained-storage/2015-05-05-alternate.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2015-05-05-alternate.png
rename to docs/design/images/case-study-chained-storage/2015-05-05-alternate.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2015-05-05.dot b/docs/design/images/case-study-chained-storage/2015-05-05.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2015-05-05.dot
rename to docs/design/images/case-study-chained-storage/2015-05-05.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2015-05-05.png b/docs/design/images/case-study-chained-storage/2015-05-05.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2015-05-05.png
rename to docs/design/images/case-study-chained-storage/2015-05-05.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2016-06-06.dot b/docs/design/images/case-study-chained-storage/2016-06-06.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2016-06-06.dot
rename to docs/design/images/case-study-chained-storage/2016-06-06.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2016-06-06.png b/docs/design/images/case-study-chained-storage/2016-06-06.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2016-06-06.png
rename to docs/design/images/case-study-chained-storage/2016-06-06.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2017-07-07.dot b/docs/design/images/case-study-chained-storage/2017-07-07.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2017-07-07.dot
rename to docs/design/images/case-study-chained-storage/2017-07-07.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2017-07-07.png b/docs/design/images/case-study-chained-storage/2017-07-07.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2017-07-07.png
rename to docs/design/images/case-study-chained-storage/2017-07-07.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2018-08-08.dot b/docs/design/images/case-study-chained-storage/2018-08-08.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2018-08-08.dot
rename to docs/design/images/case-study-chained-storage/2018-08-08.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2018-08-08.png b/docs/design/images/case-study-chained-storage/2018-08-08.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2018-08-08.png
rename to docs/design/images/case-study-chained-storage/2018-08-08.png
diff --git a/hack/generator/spec/images/case-study-chained-storage/2019-09-09.dot b/docs/design/images/case-study-chained-storage/2019-09-09.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2019-09-09.dot
rename to docs/design/images/case-study-chained-storage/2019-09-09.dot
diff --git a/hack/generator/spec/images/case-study-chained-storage/2019-09-09.png b/docs/design/images/case-study-chained-storage/2019-09-09.png
similarity index 100%
rename from hack/generator/spec/images/case-study-chained-storage/2019-09-09.png
rename to docs/design/images/case-study-chained-storage/2019-09-09.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2011-01-01.dot b/docs/design/images/case-study-fixed-storage/2011-01-01.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2011-01-01.dot
rename to docs/design/images/case-study-fixed-storage/2011-01-01.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2011-01-01.png b/docs/design/images/case-study-fixed-storage/2011-01-01.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2011-01-01.png
rename to docs/design/images/case-study-fixed-storage/2011-01-01.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2012-02-02.dot b/docs/design/images/case-study-fixed-storage/2012-02-02.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2012-02-02.dot
rename to docs/design/images/case-study-fixed-storage/2012-02-02.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2012-02-02.png b/docs/design/images/case-study-fixed-storage/2012-02-02.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2012-02-02.png
rename to docs/design/images/case-study-fixed-storage/2012-02-02.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2013-03-03.dot b/docs/design/images/case-study-fixed-storage/2013-03-03.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2013-03-03.dot
rename to docs/design/images/case-study-fixed-storage/2013-03-03.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2013-03-03.png b/docs/design/images/case-study-fixed-storage/2013-03-03.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2013-03-03.png
rename to docs/design/images/case-study-fixed-storage/2013-03-03.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2014-04-04-preview.dot b/docs/design/images/case-study-fixed-storage/2014-04-04-preview.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2014-04-04-preview.dot
rename to docs/design/images/case-study-fixed-storage/2014-04-04-preview.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2014-04-04-preview.png b/docs/design/images/case-study-fixed-storage/2014-04-04-preview.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2014-04-04-preview.png
rename to docs/design/images/case-study-fixed-storage/2014-04-04-preview.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2014-04-04.dot b/docs/design/images/case-study-fixed-storage/2014-04-04.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2014-04-04.dot
rename to docs/design/images/case-study-fixed-storage/2014-04-04.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2014-04-04.png b/docs/design/images/case-study-fixed-storage/2014-04-04.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2014-04-04.png
rename to docs/design/images/case-study-fixed-storage/2014-04-04.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2015-05-05.dot b/docs/design/images/case-study-fixed-storage/2015-05-05.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2015-05-05.dot
rename to docs/design/images/case-study-fixed-storage/2015-05-05.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2015-05-05.png b/docs/design/images/case-study-fixed-storage/2015-05-05.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2015-05-05.png
rename to docs/design/images/case-study-fixed-storage/2015-05-05.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2016-06-06.dot b/docs/design/images/case-study-fixed-storage/2016-06-06.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2016-06-06.dot
rename to docs/design/images/case-study-fixed-storage/2016-06-06.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2016-06-06.png b/docs/design/images/case-study-fixed-storage/2016-06-06.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2016-06-06.png
rename to docs/design/images/case-study-fixed-storage/2016-06-06.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2017-07-07.dot b/docs/design/images/case-study-fixed-storage/2017-07-07.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2017-07-07.dot
rename to docs/design/images/case-study-fixed-storage/2017-07-07.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2017-07-07.png b/docs/design/images/case-study-fixed-storage/2017-07-07.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2017-07-07.png
rename to docs/design/images/case-study-fixed-storage/2017-07-07.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2018-08-08.dot b/docs/design/images/case-study-fixed-storage/2018-08-08.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2018-08-08.dot
rename to docs/design/images/case-study-fixed-storage/2018-08-08.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2018-08-08.png b/docs/design/images/case-study-fixed-storage/2018-08-08.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2018-08-08.png
rename to docs/design/images/case-study-fixed-storage/2018-08-08.png
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2019-09-09.dot b/docs/design/images/case-study-fixed-storage/2019-09-09.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2019-09-09.dot
rename to docs/design/images/case-study-fixed-storage/2019-09-09.dot
diff --git a/hack/generator/spec/images/case-study-fixed-storage/2019-09-09.png b/docs/design/images/case-study-fixed-storage/2019-09-09.png
similarity index 100%
rename from hack/generator/spec/images/case-study-fixed-storage/2019-09-09.png
rename to docs/design/images/case-study-fixed-storage/2019-09-09.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2011-01-01.dot b/docs/design/images/case-study-rolling-storage/2011-01-01.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2011-01-01.dot
rename to docs/design/images/case-study-rolling-storage/2011-01-01.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2011-01-01.png b/docs/design/images/case-study-rolling-storage/2011-01-01.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2011-01-01.png
rename to docs/design/images/case-study-rolling-storage/2011-01-01.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2012-02-02.dot b/docs/design/images/case-study-rolling-storage/2012-02-02.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2012-02-02.dot
rename to docs/design/images/case-study-rolling-storage/2012-02-02.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2012-02-02.png b/docs/design/images/case-study-rolling-storage/2012-02-02.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2012-02-02.png
rename to docs/design/images/case-study-rolling-storage/2012-02-02.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2013-03-03.dot b/docs/design/images/case-study-rolling-storage/2013-03-03.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2013-03-03.dot
rename to docs/design/images/case-study-rolling-storage/2013-03-03.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2013-03-03.png b/docs/design/images/case-study-rolling-storage/2013-03-03.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2013-03-03.png
rename to docs/design/images/case-study-rolling-storage/2013-03-03.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2014-04-04-preview.dot b/docs/design/images/case-study-rolling-storage/2014-04-04-preview.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2014-04-04-preview.dot
rename to docs/design/images/case-study-rolling-storage/2014-04-04-preview.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2014-04-04-preview.png b/docs/design/images/case-study-rolling-storage/2014-04-04-preview.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2014-04-04-preview.png
rename to docs/design/images/case-study-rolling-storage/2014-04-04-preview.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2014-04-04.dot b/docs/design/images/case-study-rolling-storage/2014-04-04.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2014-04-04.dot
rename to docs/design/images/case-study-rolling-storage/2014-04-04.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2014-04-04.png b/docs/design/images/case-study-rolling-storage/2014-04-04.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2014-04-04.png
rename to docs/design/images/case-study-rolling-storage/2014-04-04.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2015-05-05.dot b/docs/design/images/case-study-rolling-storage/2015-05-05.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2015-05-05.dot
rename to docs/design/images/case-study-rolling-storage/2015-05-05.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2015-05-05.png b/docs/design/images/case-study-rolling-storage/2015-05-05.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2015-05-05.png
rename to docs/design/images/case-study-rolling-storage/2015-05-05.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2016-06-06.dot b/docs/design/images/case-study-rolling-storage/2016-06-06.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2016-06-06.dot
rename to docs/design/images/case-study-rolling-storage/2016-06-06.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2016-06-06.png b/docs/design/images/case-study-rolling-storage/2016-06-06.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2016-06-06.png
rename to docs/design/images/case-study-rolling-storage/2016-06-06.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2017-07-07.dot b/docs/design/images/case-study-rolling-storage/2017-07-07.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2017-07-07.dot
rename to docs/design/images/case-study-rolling-storage/2017-07-07.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2017-07-07.png b/docs/design/images/case-study-rolling-storage/2017-07-07.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2017-07-07.png
rename to docs/design/images/case-study-rolling-storage/2017-07-07.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2018-08-08.dot b/docs/design/images/case-study-rolling-storage/2018-08-08.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2018-08-08.dot
rename to docs/design/images/case-study-rolling-storage/2018-08-08.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2018-08-08.png b/docs/design/images/case-study-rolling-storage/2018-08-08.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2018-08-08.png
rename to docs/design/images/case-study-rolling-storage/2018-08-08.png
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2019-09-09.dot b/docs/design/images/case-study-rolling-storage/2019-09-09.dot
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2019-09-09.dot
rename to docs/design/images/case-study-rolling-storage/2019-09-09.dot
diff --git a/hack/generator/spec/images/case-study-rolling-storage/2019-09-09.png b/docs/design/images/case-study-rolling-storage/2019-09-09.png
similarity index 100%
rename from hack/generator/spec/images/case-study-rolling-storage/2019-09-09.png
rename to docs/design/images/case-study-rolling-storage/2019-09-09.png
diff --git a/hack/generator/spec/images/versioning/conversions.dot b/docs/design/images/versioning/conversions.dot
similarity index 100%
rename from hack/generator/spec/images/versioning/conversions.dot
rename to docs/design/images/versioning/conversions.dot
diff --git a/hack/generator/spec/images/versioning/conversions.png b/docs/design/images/versioning/conversions.png
similarity index 100%
rename from hack/generator/spec/images/versioning/conversions.png
rename to docs/design/images/versioning/conversions.png
diff --git a/hack/generator/spec/images/versioning/direct-conversion.png b/docs/design/images/versioning/direct-conversion.png
similarity index 100%
rename from hack/generator/spec/images/versioning/direct-conversion.png
rename to docs/design/images/versioning/direct-conversion.png
diff --git a/hack/generator/spec/images/versioning/direct-conversion.seq b/docs/design/images/versioning/direct-conversion.seq
similarity index 100%
rename from hack/generator/spec/images/versioning/direct-conversion.seq
rename to docs/design/images/versioning/direct-conversion.seq
diff --git a/hack/generator/spec/images/versioning/golden-tests-from-latest.dot b/docs/design/images/versioning/golden-tests-from-latest.dot
similarity index 100%
rename from hack/generator/spec/images/versioning/golden-tests-from-latest.dot
rename to docs/design/images/versioning/golden-tests-from-latest.dot
diff --git a/hack/generator/spec/images/versioning/golden-tests-from-latest.png b/docs/design/images/versioning/golden-tests-from-latest.png
similarity index 100%
rename from hack/generator/spec/images/versioning/golden-tests-from-latest.png
rename to docs/design/images/versioning/golden-tests-from-latest.png
diff --git a/hack/generator/spec/images/versioning/golden-tests-to-latest.dot b/docs/design/images/versioning/golden-tests-to-latest.dot
similarity index 100%
rename from hack/generator/spec/images/versioning/golden-tests-to-latest.dot
rename to docs/design/images/versioning/golden-tests-to-latest.dot
diff --git a/hack/generator/spec/images/versioning/golden-tests-to-latest.png b/docs/design/images/versioning/golden-tests-to-latest.png
similarity index 100%
rename from hack/generator/spec/images/versioning/golden-tests-to-latest.png
rename to docs/design/images/versioning/golden-tests-to-latest.png
diff --git a/hack/generator/spec/images/versioning/multiple-step-conversion.png b/docs/design/images/versioning/multiple-step-conversion.png
similarity index 100%
rename from hack/generator/spec/images/versioning/multiple-step-conversion.png
rename to docs/design/images/versioning/multiple-step-conversion.png
diff --git a/hack/generator/spec/images/versioning/multiple-step-conversion.seq b/docs/design/images/versioning/multiple-step-conversion.seq
similarity index 100%
rename from hack/generator/spec/images/versioning/multiple-step-conversion.seq
rename to docs/design/images/versioning/multiple-step-conversion.seq
diff --git a/hack/generator/spec/images/versioning/property-mapping-flowchart.dot b/docs/design/images/versioning/property-mapping-flowchart.dot
similarity index 100%
rename from hack/generator/spec/images/versioning/property-mapping-flowchart.dot
rename to docs/design/images/versioning/property-mapping-flowchart.dot
diff --git a/hack/generator/spec/images/versioning/property-mapping-flowchart.png b/docs/design/images/versioning/property-mapping-flowchart.png
similarity index 100%
rename from hack/generator/spec/images/versioning/property-mapping-flowchart.png
rename to docs/design/images/versioning/property-mapping-flowchart.png
diff --git a/hack/generator/spec/images/versioning/two-step-conversion.png b/docs/design/images/versioning/two-step-conversion.png
similarity index 100%
rename from hack/generator/spec/images/versioning/two-step-conversion.png
rename to docs/design/images/versioning/two-step-conversion.png
diff --git a/hack/generator/spec/images/versioning/two-step-conversion.seq b/docs/design/images/versioning/two-step-conversion.seq
similarity index 100%
rename from hack/generator/spec/images/versioning/two-step-conversion.seq
rename to docs/design/images/versioning/two-step-conversion.seq
diff --git a/hack/generator/spec/images/versioning/two-step-reverse-conversion.png b/docs/design/images/versioning/two-step-reverse-conversion.png
similarity index 100%
rename from hack/generator/spec/images/versioning/two-step-reverse-conversion.png
rename to docs/design/images/versioning/two-step-reverse-conversion.png
diff --git a/hack/generator/spec/images/versioning/two-step-reverse-conversion.seq b/docs/design/images/versioning/two-step-reverse-conversion.seq
similarity index 100%
rename from hack/generator/spec/images/versioning/two-step-reverse-conversion.seq
rename to docs/design/images/versioning/two-step-reverse-conversion.seq
diff --git a/hack/generator/spec/type_references_and_ownership.md b/docs/design/type-references-and-ownership.md
similarity index 100%
rename from hack/generator/spec/type_references_and_ownership.md
rename to docs/design/type-references-and-ownership.md
diff --git a/hack/generator/spec/versioning.md b/docs/design/versioning.md
similarity index 100%
rename from hack/generator/spec/versioning.md
rename to docs/design/versioning.md
diff --git a/docs/faq.md b/docs/faq.md
index 01c120ee563..411f73ecce1 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -5,9 +5,6 @@ This page provides help with the most common questions about Azure Service Opera
 ### Do I have to order the creation of resources through the operator? For instance, do I need to first create the EventHub namespace before creating the EventHub?
 No, you can issue the creation of all resources at the same time. The operator will take care of waiting and requeuing the requests until the parent resource is ready and all resources will eventually be ready.
 
-### If I need to add a new field to the spec of an existing CRD, do I need to increment the version of the CRD?
-Yes, we follow semantic versioning to preserve backward compatibility. Please follow Kubebuilder's versioning [mechanism](https://book.kubebuilder.io/multiversion-tutorial/conversion-concepts.html) for this.
-
 ### Is there a guide that talks about how to develop an operator for a new Azure service?
 There is a [step-by-step guide](/docs/howto/newoperatorguide.md) that walks you through this process.
 
diff --git a/docs/virtualmachineextension/virtualmachineextension.md b/docs/services/virtualmachineextension/virtualmachineextension.md
similarity index 100%
rename from docs/virtualmachineextension/virtualmachineextension.md
rename to docs/services/virtualmachineextension/virtualmachineextension.md